refactor(components,recipes): DLT-3043 DLT-3046 logical start/end naming with deprecated backward-compatible fallbacks (#1079)

Author: francisrupert

.claude/rules/logical-naming.md

@@ -0,0 +1,59 @@
+# Logical Naming Convention
+
+## Direction Names
+
+Use logical names in all new component code, e.g.:
+
+- `start` / `end` (inline axis — replaces `left` / `right`)
+- `blockStart` / `blockEnd` (block axis — replaces `top` / `bottom`)
+- `startIcon` / `endIcon` (replaces `leftIcon` / `rightIcon` or `alphaIcon` / `omegaIcon`)
+
+## Deprecated Slot Backward Compatibility
+
+Use the `v-if`/`v-else` pattern (NOT nested slots) for deprecated slot fallbacks:
+
+```vue
+<!-- @slot Slot for start content -->
+<slot v-if="$slots.start" name="start" />
+<!-- @slot @deprecated Use start -->
+<slot v-else name="left" />
+```
+
+For scoped slots, pass the same bindings to both:
+
+```vue
+<slot v-if="$slots.startIcon" name="startIcon" :icon-size="iconSize" />
+<slot v-else name="leftIcon" :icon-size="iconSize" />
+```
+
+Use `$slots.xxx` for the inner choice (matches nested-slot behavior: an empty `#start` still suppresses `#left`). Use `hasSlotContent($slots.xxx)` for outer visibility guards that control wrapper element rendering.
+
+## Deprecated Props
+
+Use sentinel defaults with nullish coalescing:
+
+- **String** deprecated props: `default: undefined`, resolve with `??`
+- **Boolean** deprecated props: `default: null`, resolve with `??`
+
+```js
+// In props:
+startClass: { type: String, default: '' },
+/** @deprecated Use startClass */
+leftClass: { type: String, default: undefined },
+
+// In computed:
+resolvedStartClass () {
+  return this.leftClass ?? this.startClass;
+}
+```
+
+## Deprecated Events
+
+Emit both new and old event names:
+
+```js
+onStartClick () {
+  this.$emit('start-clicked');
+  this.$emit('alpha-clicked');
+},
+```

apps/dialtone-documentation/docs/.vuepress/baseComponents/ClampedTableWrapper.vue

@@ -9,10 +9,10 @@
         root-class="d-w332"
         @keydown.escape="handleEscapeKey"
       >
-        <template #leftIcon="{ iconSize }">
+        <template #startIcon="{ iconSize }">
           <dt-icon name="search" :size="iconSize" />
         </template>
-        <template v-if="inputSearchValue.length !== 0" #rightIcon>
+        <template v-if="inputSearchValue.length !== 0" #endIcon>
           <dt-stack class="d-pr1">
             <dt-button
               v-dt-tooltip="`Clear`"
@@ -22,7 +22,7 @@
               aria-label="Clear search"
               @click="clearSearch"
             >
-              <template #icon>
+              <template #startIcon>
                 <dt-icon name="close" size="100" />
               </template>
             </dt-button>
@@ -58,12 +58,11 @@
         class="dialtone-doc-table-clamped__more-btn d-bgc-secondary d-bs-sm"
         kind="muted"
         importance="outlined"
-        icon-position="right"
         size="sm"
         @click="() => handleExpand(scrollRef)"
       >
         {{ buttonLabel }}
-        <template #icon="{ iconSize }">
+        <template #endIcon="{ iconSize }">
           <dt-icon :name="iconName" :size="iconSize" />
         </template>
       </dt-button>

apps/dialtone-documentation/docs/.vuepress/baseComponents/CodeExampleTabs.vue

@@ -63,12 +63,11 @@
         class="code-example-tab-group__more-btn d-bgc-secondary d-bs-sm"
         kind="muted"
         importance="outlined"
-        icon-position="right"
         size="sm"
         @click="expandCodeBlocks"
       >
         Show all
-        <template #icon="{ iconSize }">
+        <template #endIcon="{ iconSize }">
           <dt-icon name="arrow-down" :size="iconSize" />
         </template>
       </dt-button>

apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentVueApi.vue

@@ -79,36 +79,59 @@ const highlightedImport = computed(() => {
   return Prism.highlight(importStatement.value, Prism.languages.javascript, 'javascript');
 });
 
+const isDeprecated = (item) => {
+  return item.tags?.deprecated?.length > 0 ||
+    /(@deprecated|deprecated[,)])/i.test(item.description || '');
+};
+
+const deprecationMessage = (item) => {
+  const tag = item.tags?.deprecated?.[0]?.description;
+  if (tag) return tag;
+  const desc = item.description || '';
+  const match = desc.match(/deprecated,?\s*use\s+([\w.]+)/i) ||
+    desc.match(/@deprecated\s+Use\s+([\w.]+)/i);
+  return match ? `Use ${match[1]}` : null;
+};
+
 const docSlots = componentDocs.find(f => isSameComponentName(f.displayName))
   ?.slots?.map((item) => {
     return {
       name: item.name,
-      description: item.description,
+      description: isDeprecated(item) ? undefined : item.description,
+      deprecated: isDeprecated(item),
+      deprecatedMessage: deprecationMessage(item),
     };
   });
 
+const resolveConstantRef = (rawDefault, values) => {
+  const match = rawDefault.match(/^[A-Z][A-Z_]*\.[A-Z][A-Z_]*$/);
+  if (!match) return rawDefault;
+  const key = rawDefault.split('.')[1].toLowerCase().replace(/_/g, '-');
+  const found = values.find(v => v === key || v === key.replace(/-/g, '_'));
+  if (found) return found;
+  if (key === 'none' && values.includes('null')) return 'null';
+  return rawDefault;
+};
+
 const resolveDefaultValue = (rawDefault, values) => {
   if (!rawDefault) return rawDefault;
   if (rawDefault === 'undefined') return null;
   if (/getUniqueString\(\)/.test(rawDefault)) return 'generated unique ID';
   if (!values?.length) return rawDefault;
-  // Match constant references like DT_MODE_ISLAND_TYPES.INVERTED
-  const match = rawDefault.match(/^[A-Z][A-Z_]*\.[A-Z][A-Z_]*$/);
-  if (!match) return rawDefault;
-  const key = rawDefault.split('.')[1].toLowerCase().replace(/_/g, '-');
-  return values.find(v => v === key || v === key.replace(/-/g, '_'))
-    ?? (key === 'none' && values.includes('null') ? 'null' : rawDefault);
+  return resolveConstantRef(rawDefault, values);
 };
 
 const docProps = componentDocs.find(f => isSameComponentName(f.displayName))
   ?.props?.map((item) => {
     return {
-      name: item?.name,
-      description: item?.description,
-      type: item?.type?.name,
-      defaultValue: resolveDefaultValue(item?.defaultValue?.value, item?.values),
-      values: item?.values,
-      required: item?.required,
+      name: item.name,
+      description: item.description,
+      type: item.type?.name,
+      defaultValue: resolveDefaultValue(item.defaultValue?.value, item.values),
+      values: item.values,
+      required: item.required,
+      deprecated: isDeprecated(item),
+      deprecatedMessage: deprecationMessage(item),
     };
   });
 
@@ -118,6 +141,8 @@ const docEvents = componentDocs.find(f => isSameComponentName(f.displayName))
       name: item.name,
       description: item.description,
       type: item.type?.names.join(' '),
+      deprecated: isDeprecated(item),
+      deprecatedMessage: deprecationMessage(item),
     };
   });
 </script>

apps/dialtone-documentation/docs/.vuepress/baseComponents/ComponentVueApiTable.vue

@@ -40,67 +40,83 @@
         </thead>
         <tbody>
           <tr
-            v-for="({ name, description, type, defaultValue, values, required }) in sortedTableDataByName"
-            :key="name"
+            v-for="item in sortedTableDataByName"
+            :key="item.name"
             class="d-va-baseline"
           >
             <th scope="row">
               <dt-stack gap="300">
                 <span>
                   <code class="d-code--sm d-docsite-code">
-                    {{ name }}
+                    {{ item.name }}
                   </code>
                 </span>
                 <div
-                  v-if="required"
+                  v-if="item.required"
                   class="d-fc-critical d-fw-normal"
                 >
                   required
                 </div>
+                <span v-if="item.deprecated">
+                  <dt-badge
+                    type="critical"
+                    kind="label"
+                    text="Deprecated"
+                  />
+                </span>
               </dt-stack>
             </th>
 
             <td v-if="withDefault">
-              <code v-if="defaultValue" class="d-code--sm d-docsite-code">
-                {{ defaultValue }}
+              <code v-if="item.defaultValue" class="d-code--sm d-docsite-code">
+                {{ item.defaultValue }}
               </code>
             </td>
 
             <td class="vue-api-table">
               <dt-stack gap="350">
                 <dt-stack
-                  v-if="values"
+                  v-if="item.values"
                   direction="row"
                   align="baseline"
                   class="d-fw-wrap"
                   gap="350"
                 >
                   <template
-                    v-for="(value, index) in values"
-                    :key="`${name} ${value}`"
+                    v-for="(value, index) in item.values"
+                    :key="`${item.name} ${value}`"
                   >
                     <dt-text v-if="index > 0" tone="muted" as="span" kind="body" size="xs">
                       |
                     </dt-text>
                     <code class="d-code--sm d-docsite-code">"{{ value }}"</code>
                   </template>
                 </dt-stack>
-                <span v-else-if="type">
+                <span v-else-if="item.type">
                   <code class="d-code--sm d-docsite-code">
-                    {{ type }}
+                    {{ item.type }}
                   </code>
                 </span>
                 <dt-text
-                  v-if="description"
+                  v-if="item.description"
                   as="p"
                   kind="body"
                   size="sm"
                   wrap="balance"
                 >
                   <markdown-render
-                    :markdown="description"
+                    :markdown="item.description"
                   />
                 </dt-text>
+                <dt-text
+                  v-if="item.deprecated && item.deprecatedMessage"
+                  as="p"
+                  kind="body"
+                  size="sm"
+                  class="d-fc-critical"
+                >
+                  {{ item.deprecatedMessage }}
+                </dt-text>
               </dt-stack>
             </td>
           </tr>
@@ -141,16 +157,14 @@ const sortDataByKey = (data, nameKey, requiredKey) => {
   return data.sort((a, b) => {
     const aIsRequired = !!a[requiredKey];
     const bIsRequired = !!b[requiredKey];
+    const aIsDeprecated = !!a.deprecated;
+    const bIsDeprecated = !!b.deprecated;
 
-    // always have required at top
-    if (aIsRequired && !bIsRequired) {
-      return -1;
-    } else if (!aIsRequired && bIsRequired) {
-      return 1;
-    } else {
-      if (a[nameKey] < b[nameKey]) return -1;
-      if (a[nameKey] > b[nameKey]) return 1;
-    }
+    // Required first, deprecated last, then alphabetical
+    if (aIsRequired !== bIsRequired) return aIsRequired ? -1 : 1;
+    if (aIsDeprecated !== bIsDeprecated) return aIsDeprecated ? 1 : -1;
+    if (a[nameKey] < b[nameKey]) return -1;
+    if (a[nameKey] > b[nameKey]) return 1;
     return 0;
   });
 };

apps/dialtone-documentation/docs/.vuepress/baseComponents/CopyButton.vue

@@ -11,7 +11,7 @@
         kind="muted"
         @click="copyToClipboard"
       >
-        <template #icon="{ iconSize }">
+        <template #startIcon="{ iconSize }">
           <dt-icon
             name="copy"
             :size="iconSize"

apps/dialtone-documentation/docs/.vuepress/baseComponents/IconPopover.vue

@@ -14,12 +14,11 @@
       <dt-button
         class="dialtone-icon-grid__item d-gg8"
         label-class="d-fl-grow-unset"
-        icon-position="top"
         importance="clear"
         kind="muted"
         :active="modelValue"
       >
-        <template #icon>
+        <template #blockStartIcon>
           <dt-icon
             :name="iconName"
             size="600"

apps/dialtone-documentation/docs/.vuepress/baseComponents/tokens/TokensBar.vue

@@ -11,10 +11,10 @@
       autocomplete="off"
       @keyup="searchToken"
     >
-      <template #leftIcon>
+      <template #startIcon>
         <dt-icon name="search" size="300" />
       </template>
-      <template #rightIcon>
+      <template #endIcon>
         <dt-button
           v-if="hasSearchTerm"
           id="search-input-button-close"
@@ -25,7 +25,7 @@
           aria-label="Clear search"
           @click="resetSearch"
         >
-          <template #icon>
+          <template #startIcon>
             <dt-icon name="close" size="200" />
           </template>
         </dt-button>
@@ -60,12 +60,11 @@
         v-dt-tooltip:top-end="shareLinkTooltip"
         importance="clear"
         kind="muted"
-        icon-position="left"
         class="d-ml-auto"
         @click="copyURLToClipboard"
       >
         Share Search Filter
-        <template #icon="{ iconSize }">
+        <template #startIcon="{ iconSize }">
           <dt-icon
             name="link-2"
             :size="iconSize"

apps/dialtone-documentation/docs/.vuepress/exampleComponents/ExampleProfileCard.vue

@@ -28,19 +28,19 @@
     </dt-stack>
     <dt-stack gap="400" direction="row" justify="between">
       <dt-button class="d-fl1" kind="muted" importance="outlined">
-        <template #icon="{ iconSize }">
+        <template #startIcon="{ iconSize }">
           <dt-icon-phone :size="iconSize" />
         </template>
         Call
       </dt-button>
       <dt-button class="d-fl1" kind="muted" importance="outlined">
-        <template #icon="{ iconSize }">
+        <template #startIcon="{ iconSize }">
           <dt-icon-quick-reply :size="iconSize" />
         </template>
         Message
       </dt-button>
       <dt-button class="d-fl1" kind="muted" importance="outlined">
-        <template #icon="{ iconSize }">
+        <template #startIcon="{ iconSize }">
           <dt-icon-video :size="iconSize" />
         </template>
         Meet