docs(combinator): DLT-3424 bridge logical to physical naming (#1273)

Author: francisrupert

.claude/rules/logical-naming.md

@@ -69,3 +69,31 @@ onStartClick () {
   this.$emit('alpha-clicked');
 },
 ```
+
+## Description Prose
+
+**Identifiers stay logical. Descriptions become bilingual.**
+
+When writing a JSDoc comment, slot description, or doc-page prose that mentions a logical direction, always add the LTR-default physical equivalent as an `(aka <physical>)` parenthetical. This helps consumers mid-migration anchor the logical term to a physical one without requiring them to look it up.
+
+| Logical phrase in description | Bridged form |
+|-------------------------------|--------------|
+| `block-start side` / `block-start edge` | `block-start side (aka top)` |
+| `block-end side` / `block-end edge` | `block-end side (aka bottom)` |
+| `inline-start side` / `inline-start edge` | `inline-start side (aka left)` |
+| `inline-end side` / `inline-end edge` | `inline-end side (aka right)` |
+| `block axis` | `block axis (aka top/bottom)` |
+| `inline axis` | `inline axis (aka left/right)` |
+
+Rules:
+
+- Parenthetical is lowercase: `(aka top)` not `(AKA top)`
+- Placed inside the sentence, before the period: `… side (aka top). Overrides…`
+- Bridge the first mention in a JSDoc block only — leave subsequent `Overrides …` sentences as-is
+- Drop legacy qualifiers: `(top/bottom in horizontal writing mode)` → `(aka top/bottom)`, `in LTR` → delete
+
+## Combinator Filter
+
+The Combinator prop/slot search uses `packages/combinator/src/lib/logical_aliases.js` as its canonical alias map. In `option_bar.vue`, `tokenizeName` splits each prop/slot name on camelCase boundaries and recognizes compound tokens (`block-start`, `inline-end`, etc.) derived from the alias map keys. `getSearchCorpus` expands those tokens via `logical_aliases.js` to build a precomputed search corpus. `filterCorpora` matches the user's query against that corpus. Searching `"top"` finds `borderWidthBlockStart`, `paddingBlockStart`, etc. automatically.
+
+**When adding new logical-naming vocabulary** (e.g. a new axis concept beyond `block`/`inline`), add the new token and its physical aliases to `logical_aliases.js`. No per-component or per-prop changes needed — the filter picks it up automatically for any component that uses the new token in its prop/slot names.

apps/dialtone-documentation/docs/components/prose.md

@@ -205,7 +205,7 @@ Unordered and ordered lists can be freely nested inside each other, with each le
 
 ### Blockquote
 
-Blockquotes are visually offset with an inline-start border and muted color, supporting multi-paragraph content, nesting, and attributed citations.
+Blockquotes are visually offset with an inline-start (aka left) border and muted color, supporting multi-paragraph content, nesting, and attributed citations.
 
 ```vue demo
 <!-- @wrapper -->

apps/dialtone-documentation/docs/components/scrollbar.md

@@ -137,10 +137,10 @@ In addition to using directive arguments for scrollbar visibility (`:always`, `:
 | --- | --- | --- | --- |
 | `showScrollbar` | `'enter' \| 'always' \| 'scroll' \| 'move'` | `'enter'` | Scrollbar visibility mode |
 | `offset` | `Object` | `null` | Offset configuration for scrollbar positioning |
-| `offset.blockStart` | `number \| string` | `undefined` | Insets vertical scrollbar from the block-start edge |
-| `offset.blockEnd` | `number \| string` | `undefined` | Insets horizontal scrollbar from the block-end edge |
-| `offset.inlineStart` | `number \| string` | `undefined` | Insets horizontal scrollbar from the inline-start edge |
-| `offset.inlineEnd` | `number \| string` | `undefined` | Insets vertical scrollbar from the inline-end edge |
+| `offset.blockStart` | `number \| string` | `undefined` | Insets vertical scrollbar from the block-start (aka top) edge |
+| `offset.blockEnd` | `number \| string` | `undefined` | Insets horizontal scrollbar from the block-end (aka bottom) edge |
+| `offset.inlineStart` | `number \| string` | `undefined` | Insets horizontal scrollbar from the inline-start (aka left) edge |
+| `offset.inlineEnd` | `number \| string` | `undefined` | Insets vertical scrollbar from the inline-end (aka right) edge |
 | `blockClasses` | `string` | `undefined` | CSS classes to apply to the vertical scrollbar |
 | `inlineClasses` | `string` | `undefined` | CSS classes to apply to the horizontal scrollbar |
 
@@ -162,10 +162,10 @@ The `offset` option allows you to adjust the positioning of scrollbars to accomm
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `blockStart` | `number \| string` | Insets vertical scrollbar from the block-start edge |
-| `blockEnd` | `number \| string` | Insets horizontal scrollbar from the block-end edge |
-| `inlineStart` | `number \| string` | Insets horizontal scrollbar from the inline-start edge |
-| `inlineEnd` | `number \| string` | Insets vertical scrollbar from the inline-end edge |
+| `blockStart` | `number \| string` | Insets vertical scrollbar from the block-start (aka top) edge |
+| `blockEnd` | `number \| string` | Insets horizontal scrollbar from the block-end (aka bottom) edge |
+| `inlineStart` | `number \| string` | Insets horizontal scrollbar from the inline-start (aka left) edge |
+| `inlineEnd` | `number \| string` | Insets vertical scrollbar from the inline-end (aka right) edge |
 
 #### Numeric Values (Auto-converted to px)
 

apps/dialtone-documentation/docs/utilities/spacing/margin.md

@@ -8,7 +8,7 @@ keywords: ["outer spacing", "gap", "offset", "margin inline start", "margin inli
 >
 > Avoid applying margins directly. Lean toward using layout components like [Stack](/components/stack/) for consistent and maintainable spacing **between** elements.
 
-Use `d-m-{stop}` to set margin using spacing token stops. The number references the spacing token (`d-m-100` = `--dt-spacing-100` = 8px). Logical property aliases are also available: `d-mbs-{stop}` (margin-block-start), `d-mbe-{stop}` (margin-block-end), `d-mis-{stop}` (margin-inline-start), `d-mie-{stop}` (margin-inline-end).
+Use `d-m-{stop}` to set margin using spacing token stops. The number references the spacing token (`d-m-100` = `--dt-spacing-100` = 8px). Logical property aliases are also available: `d-mbs-{stop}` (margin-block-start, aka top), `d-mbe-{stop}` (margin-block-end, aka bottom), `d-mis-{stop}` (margin-inline-start, aka left), `d-mie-{stop}` (margin-inline-end, aka right).
 
 ## Add Margin to All Sides
 
@@ -67,7 +67,7 @@ Auto margins allow an element to fill a remaining space within an object. This i
 
 ## Classes
 
-Margins can be added using `d-m-{stop}` or directional classes like `d-m{t|r|b|l|y|x}-{stop}`. Logical property aliases are also available: `d-mbs-{stop}` (margin-block-start), `d-mbe-{stop}` (margin-block-end), `d-mis-{stop}` (margin-inline-start), `d-mie-{stop}` (margin-inline-end).
+Margins can be added using `d-m-{stop}` or directional classes like `d-m{t|r|b|l|y|x}-{stop}`. Logical property aliases are also available: `d-mbs-{stop}` (margin-block-start, aka top), `d-mbe-{stop}` (margin-block-end, aka bottom), `d-mis-{stop}` (margin-inline-start, aka left), `d-mie-{stop}` (margin-inline-end, aka right).
 
 It is highly recommended to use the [DtStack component](/components/stack.md) prior to applying margins individually.
 

apps/dialtone-documentation/docs/utilities/spacing/padding.md

@@ -47,7 +47,7 @@ Use `d-p-{stop}` to set padding using spacing token stops. The number references
 
 ## Classes
 
-Padding can be added to an element by using `d-p-{stop}` or a directional class like `d-p{t|r|b|l|y|x}-{stop}`. Logical property aliases are also available: `d-pbs-{stop}` (padding-block-start), `d-pbe-{stop}` (padding-block-end), `d-pis-{stop}` (padding-inline-start), `d-pie-{stop}` (padding-inline-end).
+Padding can be added to an element by using `d-p-{stop}` or a directional class like `d-p{t|r|b|l|y|x}-{stop}`. Logical property aliases are also available: `d-pbs-{stop}` (padding-block-start, aka top), `d-pbe-{stop}` (padding-block-end, aka bottom), `d-pis-{stop}` (padding-inline-start, aka left), `d-pie-{stop}` (padding-inline-end, aka right).
 
 It is highly recommended to use the [DtBox component](/components/box.md) before applying padding individually.
 

packages/combinator/src/components/option_bar/option_bar.vue

@@ -139,6 +139,7 @@ import { computed, ref, nextTick } from 'vue';
 import { OPTIONS_UPDATE_EVENT } from '@/src/lib/constants';
 import { getControlByMemberType, getControlByValue } from '@/src/lib/control';
 import { isIconSlot } from '@/src/lib/icons';
+import { LOGICAL_ALIASES } from '@/src/lib/logical_aliases';
 import { DtStack, DtTabGroup, DtTab, DtTabPanel } from '@dialpad/dialtone-vue';
 import { DtIconSearch } from '@dialpad/dialtone-icons/vue';
 
@@ -186,14 +187,42 @@ function normalizeForSearch (str) {
   return str.toLowerCase().replace(/[\s\-_]/g, '');
 }
 
-function filterMembers (members) {
+// Derived from LOGICAL_ALIASES keys so tokenizeName stays in sync automatically.
+const COMPOUND_TOKENS = new Set(Object.keys(LOGICAL_ALIASES).filter(k => k.includes('-')));
+
+function tokenizeName (name) {
+  const parts = name.replace(/([A-Z])/g, ' $1').trim().toLowerCase().split(/\s+/);
+  const tokens = [];
+  for (let i = 0; i < parts.length; i++) {
+    const compound = parts[i + 1] ? `${parts[i]}-${parts[i + 1]}` : null;
+    if (compound && COMPOUND_TOKENS.has(compound)) {
+      tokens.push(compound);
+      i++;
+    } else {
+      tokens.push(parts[i]);
+    }
+  }
+  return tokens;
+}
+
+function getSearchCorpus (name) {
+  const tokens = tokenizeName(name);
+  const aliases = tokens.flatMap(t => LOGICAL_ALIASES[t] ?? []);
+  return [name, ...tokens, ...aliases].map(normalizeForSearch).join(' ');
+}
+
+// Pre-compute corpora once per member list so per-keystroke filtering is just a substring scan.
+const propCorpora = computed(() => (props.info.props ?? []).map(m => ({ member: m, corpus: getSearchCorpus(m.name) })));
+const slotCorpora = computed(() => (props.info.slots ?? []).map(m => ({ member: m, corpus: getSearchCorpus(m.name) })));
+
+function filterCorpora (corpora) {
   const q = normalizeForSearch(searchQuery.value);
-  if (q.length < 2) return members;
-  return members.filter(m => normalizeForSearch(m.name).includes(q));
+  if (q.length < 2) return corpora.map(({ member }) => member);
+  return corpora.filter(({ corpus }) => corpus.includes(q)).map(({ member }) => member);
 }
 
-const filteredProps = computed(() => filterMembers(props.info.props));
-const filteredSlots = computed(() => filterMembers(props.info.slots));
+const filteredProps = computed(() => filterCorpora(propCorpora.value));
+const filteredSlots = computed(() => filterCorpora(slotCorpora.value));
 
 /**
  * Gets an array of controls for a binding.

packages/combinator/src/lib/logical_aliases.js

@@ -0,0 +1,16 @@
+// Maps logical CSS naming tokens to their LTR-default physical aliases.
+// Used by option_bar.vue so consumers can search "top", "bottom", "left", "right",
+// "vertical", or "horizontal" and find logical-named props and slots.
+//
+// Each entry must be self-contained: a compound key like 'block-start' must list
+// every alias a *BlockStart prop should match. The tokenizer does NOT fall back
+// to the base 'block' entry — that would bleed opposite-edge aliases ('bottom')
+// into block-start results.
+export const LOGICAL_ALIASES = {
+  'block-start': ['top', 'vertical'],
+  'block-end': ['bottom', 'vertical'],
+  'inline-start': ['left', 'horizontal'],
+  'inline-end': ['right', 'horizontal'],
+  block: ['top', 'bottom', 'vertical'],
+  inline: ['left', 'right', 'horizontal'],
+};

packages/dialtone-vue/components/Box/Box.vue

@@ -85,42 +85,42 @@ const props = defineProps({
   borderWidth: { type: String, default: undefined, validator: borderWidthValidator },
 
   /**
-   * Border width on the block axis (top/bottom in horizontal writing mode).
+   * Border width on the block axis (aka top/bottom).
    * Overrides `borderWidth` for block sides.
    * @values 0, 50, 100, 150, 200, 300, 400
    */
   borderWidthBlock: { type: String, default: undefined, validator: borderWidthValidator },
 
   /**
-   * Border width on the block-end side.
+   * Border width on the block-end side (aka bottom).
    * Overrides `borderWidthBlock` and `borderWidth` for block-end.
    * @values 0, 50, 100, 150, 200, 300, 400
    */
   borderWidthBlockEnd: { type: String, default: undefined, validator: borderWidthValidator },
 
   /**
-   * Border width on the block-start side.
+   * Border width on the block-start side (aka top).
    * Overrides `borderWidthBlock` and `borderWidth` for block-start.
    * @values 0, 50, 100, 150, 200, 300, 400
    */
   borderWidthBlockStart: { type: String, default: undefined, validator: borderWidthValidator },
 
   /**
-   * Border width on the inline axis (left/right in LTR).
+   * Border width on the inline axis (aka left/right).
    * Overrides `borderWidth` for inline sides.
    * @values 0, 50, 100, 150, 200, 300, 400
    */
   borderWidthInline: { type: String, default: undefined, validator: borderWidthValidator },
 
   /**
-   * Border width on the inline-end side.
+   * Border width on the inline-end side (aka right).
    * Overrides `borderWidthInline` and `borderWidth` for inline-end.
    * @values 0, 50, 100, 150, 200, 300, 400
    */
   borderWidthInlineEnd: { type: String, default: undefined, validator: borderWidthValidator },
 
   /**
-   * Border width on the inline-start side.
+   * Border width on the inline-start side (aka left).
    * Overrides `borderWidthInline` and `borderWidth` for inline-start.
    * @values 0, 50, 100, 150, 200, 300, 400
    */
@@ -133,55 +133,55 @@ const props = defineProps({
   padding: { type: String, default: undefined, validator: spacingValidator },
 
   /**
-   * Padding on the block axis (top/bottom in horizontal writing mode).
+   * Padding on the block axis (aka top/bottom).
    * Overrides `padding` for the block axis.
    * @values 0, 1, 25, 50, 75, 100, 125, 150, 175, 200, 250, 300, 350, 400, 450, 500, 525, 550, 600, 650, 700, 750, 800
    */
   paddingBlock: { type: String, default: undefined, validator: spacingValidator },
 
   /**
-   * Padding on the block-end side.
+   * Padding on the block-end side (aka bottom).
    * Overrides `paddingBlock` and `padding` for block-end.
    * @values 0, 1, 25, 50, 75, 100, 125, 150, 175, 200, 250, 300, 350, 400, 450, 500, 525, 550, 600, 650, 700, 750, 800
    */
   paddingBlockEnd: { type: String, default: undefined, validator: spacingValidator },
 
   /**
-   * Padding on the block-start side.
+   * Padding on the block-start side (aka top).
    * Overrides `paddingBlock` and `padding` for block-start.
    * @values 0, 1, 25, 50, 75, 100, 125, 150, 175, 200, 250, 300, 350, 400, 450, 500, 525, 550, 600, 650, 700, 750, 800
    */
   paddingBlockStart: { type: String, default: undefined, validator: spacingValidator },
 
   /**
-   * Padding on the inline axis (left/right in LTR).
+   * Padding on the inline axis (aka left/right).
    * Overrides `padding` for the inline axis.
    * @values 0, 1, 25, 50, 75, 100, 125, 150, 175, 200, 250, 300, 350, 400, 450, 500, 525, 550, 600, 650, 700, 750, 800
    */
   paddingInline: { type: String, default: undefined, validator: spacingValidator },
 
   /**
-   * Padding on the inline-end side.
+   * Padding on the inline-end side (aka right).
    * Overrides `paddingInline` and `padding` for inline-end.
    * @values 0, 1, 25, 50, 75, 100, 125, 150, 175, 200, 250, 300, 350, 400, 450, 500, 525, 550, 600, 650, 700, 750, 800
    */
   paddingInlineEnd: { type: String, default: undefined, validator: spacingValidator },
 
   /**
-   * Padding on the inline-start side.
+   * Padding on the inline-start side (aka left).
    * Overrides `paddingInline` and `padding` for inline-start.
    * @values 0, 1, 25, 50, 75, 100, 125, 150, 175, 200, 250, 300, 350, 400, 450, 500, 525, 550, 600, 650, 700, 750, 800
    */
   paddingInlineStart: { type: String, default: undefined, validator: spacingValidator },
 
   /**
-   * Block size (height in horizontal writing mode). Maps to --dt-layout-* tokens.
+   * Block size (aka height). Maps to --dt-layout-* tokens.
    * @values 0, 1px, 2px, 8px, 25, 20px, 24px, 50, 75, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 10p, 20p, 25p, 30p, 33p, 40p, 50p, 60p, 66p, 70p, 75p, 80p, 90p, 95p, 100p
    */
   blockSize: { type: String, default: undefined, validator: layoutValidator },
 
   /**
-   * Inline size (width in horizontal writing mode). Maps to --dt-layout-* tokens.
+   * Inline size (aka width). Maps to --dt-layout-* tokens.
    * @values 0, 1px, 2px, 8px, 25, 20px, 24px, 50, 75, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 10p, 20p, 25p, 30p, 33p, 40p, 50p, 60p, 66p, 70p, 75p, 80p, 90p, 95p, 100p
    */
   inlineSize: { type: String, default: undefined, validator: layoutValidator },

packages/dialtone-vue/components/Button/Button.vue

@@ -57,7 +57,7 @@
         startIconClass,
       ]"
     >
-      <!-- @slot Icon displayed at the start (left in LTR) of the button -->
+      <!-- @slot Icon displayed at the start (aka left) of the button -->
       <slot
         name="startIcon"
         :icon-size="iconSize"
@@ -107,7 +107,7 @@
         endIconClass,
       ]"
     >
-      <!-- @slot Icon displayed at the end (right in LTR) of the button -->
+      <!-- @slot Icon displayed at the end (aka right) of the button -->
       <slot
         name="endIcon"
         :icon-size="iconSize"
@@ -334,15 +334,15 @@ export default {
     },
 
     /**
-     * Used to customize the block-start icon container
+     * Used to customize the block-start (aka top) icon container
      */
     blockStartIconClass: {
       type: [String, Array, Object],
       default: '',
     },
 
     /**
-     * Used to customize the block-end icon container
+     * Used to customize the block-end (aka bottom) icon container
      */
     blockEndIconClass: {
       type: [String, Array, Object],

packages/dialtone-vue/components/ItemLayout/ItemLayout.vue

@@ -158,15 +158,15 @@ export default {
     },
 
     /**
-     * Set the class for the block-end section.
+     * Set the class for the block-end section (aka bottom).
      */
     blockEndClass: {
       type: [String, Array, Object],
       default: '',
     },
 
     /**
-     * Set the class for the block-end section.
+     * Set the class for the block-end section (aka bottom).
      * @deprecated Use blockEndClass
      */
     bottomClass: {