srcdev-nuxt-components 9.3.12 → 9.3.13

package/app/components/05.forms/toggle-switch/ToggleSwitchCore.vue

@@ -96,17 +96,24 @@ const toggleSwitchValue = () => {
   }
 
   .toggle-switch-wrapper {
-    --_icon-on-opacity: 0;
-    --_icon-off-opacity: 1;
+    /* --_icon-font-size, --_switch-padding, --_toggle-symbol-border-width are the only locals
+       actually read anywhere below — --_icon-on-opacity, --_icon-off-opacity,
+       --_symbol-background-color, --_symbol-margin-inline-start, --_symbol-checked-offset were
+       declared here but never referenced by any property in this file; removed as dead code
+       rather than migrated, since migrating an unread token would just create a new unread
+       public one. */
     --_icon-font-size: 2.4rem;
-    --_symbol-background-color: var(--blue-10);
-    --_symbol-margin-inline-start: 0;
-    --_symbol-checked-offset: calc(var(--input-toggle-symbol-size) * 0.75);
-
-    /* New vars */
     --_switch-padding: 0.2rem;
     --_toggle-symbol-border-width: 0.1rem;
 
+    /* Public --toggle-switch-* tokens, inline-fallback to the shared --theme-* tokens (see
+       theming-component-token-pattern.md) — overriding one here doesn't touch every other
+       themed input/control that also reads --theme-checkbox-symbol-surface/--theme-border. */
+    --_surface: var(--toggle-switch-surface, var(--theme-checkbox-symbol-surface));
+    --_surface-hover: var(--toggle-switch-surface-hover, var(--theme-surface-subtle));
+    --_border: var(--toggle-switch-border, var(--theme-border));
+    --_border-focus: var(--toggle-switch-border-focus, var(--theme-border-focus));
+
     display: flex;
     flex-direction: column;
 
@@ -117,7 +124,7 @@ const toggleSwitchValue = () => {
 
       &:focus-visible {
         + .symbol-wrapper {
-          outline: var(--form-element-outline-width-focus) solid var(--theme-border-focus);
+          outline: var(--form-element-outline-width-focus) solid var(--_border-focus);
           outline-offset: var(--form-element-outline-offset-focus);
         }
       }
@@ -137,15 +144,15 @@ const toggleSwitchValue = () => {
         outline var(--theme-form-transition-duration) linear;
 
       /* UI */
-      background-color: var(--theme-checkbox-symbol-surface);
-      border: var(--form-element-border-width) solid var(--theme-border);
+      background-color: var(--_surface);
+      border: var(--form-element-border-width) solid var(--_border);
       outline: var(--form-element-outline-width) solid transparent;
       border-radius: 100vw;
       width: 72px;
       padding: calc(var(--input-toggle-wrapper-padding) + var(--input-toggle-symbol-outline-width));
 
       &:hover {
-        background-color: var(--theme-surface-subtle);
+        background-color: var(--_surface-hover);
         cursor: pointer;
       }
 
@@ -163,16 +170,16 @@ const toggleSwitchValue = () => {
 
         /* UI */
         /* padding: calc(calc(var(--input-toggle-symbol-size) - var(--_icon-font-size)) / 2); */
-        border: var(--input-toggle-symbol-border-width) solid var(--theme-text);
+        border: var(--input-toggle-symbol-border-width) solid var(--toggle-switch-symbol-border, var(--theme-text));
         outline: var(--input-toggle-symbol-outline-width) solid transparent;
         border-radius: 100vw;
-        background-color: var(--theme-on-surface);
+        background-color: var(--toggle-switch-symbol-surface-off, var(--theme-on-surface));
         transition:
           translate 0.4s ease,
           background-color 0.4s linear;
 
         &.checked {
-          background-color: var(--theme-surface);
+          background-color: var(--toggle-switch-symbol-surface-on, var(--theme-surface));
           /* left: calc(
             100% - var(--input-toggle-symbol-size) - var(--_switch-padding) - (2 * var(--_toggle-symbol-border-width))
           ); */
@@ -202,11 +209,11 @@ const toggleSwitchValue = () => {
             color var(--theme-form-transition-duration);
 
           &.icon-on {
-            color: var(--theme-on-surface);
+            color: var(--toggle-switch-icon-on-color, var(--theme-on-surface));
           }
 
           &.icon-off {
-            color: var(--theme-surface);
+            color: var(--toggle-switch-icon-off-color, var(--theme-surface));
           }
 
           &.active {

package/app/components/05.forms/triple-toggle-switch/CONSUMER-STYLING.md

@@ -0,0 +1,72 @@
+# TripleToggleSwitchCore — Consumer Styling Guide
+
+## Public token API
+
+Every colour token below is `var(--triple-toggle-switch-*, {default})` — set the
+`--triple-toggle-switch-*` name to override just this component; leave it unset and it inherits
+the shared `--theme-*` token every other themed component also falls back to. See
+`theming-component-token-pattern.md` for why this two-tier shape exists.
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--triple-toggle-switch-surface` | `var(--theme-input-surface)` | Wrapper background |
+| `--triple-toggle-switch-border` | `var(--theme-border)` | Wrapper border colour |
+| `--triple-toggle-switch-ring-focus` | `var(--theme-ring)` | Wrapper outline colour on `:focus-visible` |
+| `--triple-toggle-switch-marker-surface` | `var(--theme-input-surface)` | Selected-option marker background, when none of the `system`/`light`/`dark` `:has()` overrides below match |
+| `--triple-toggle-switch-marker-border` | `light-dark(var(--slate-10), var(--slate-00))` | Selected-option marker border colour |
+| `--triple-toggle-switch-option-border` | `light-dark(#00000025, #ffffff50)` | Each option's resting border colour |
+| `--triple-toggle-switch-option-border-hover` | `light-dark(var(--slate-10), var(--slate-00))` | Each option's outline colour on hover |
+| `--triple-toggle-switch-option-ring-focus` | `var(--theme-ring)` | Each option's outline colour on `:focus-visible` |
+| `--triple-toggle-switch-option-icon-color` | `light-dark(var(--slate-10), var(--slate-03))` | Option icon colour, resting (shared by the `.system`/`.light`/`.dark` selectors — see note) |
+| `--triple-toggle-switch-option-icon-color-active` | `var(--slate-00)` | Option icon colour, selected |
+
+> **Two bugs fixed in this migration**:
+>
+> 1. `--triple-toggle-switch-marker-surface` replaces a reference to `--theme-form-checkbox-bg`, a
+>    token declared nowhere in this layer at all — an undefined `var()` with no fallback silently
+>    resolves to the property's initial value, so the marker had no visible background whenever
+>    none of the value-specific `:has()` overrides matched. Two more dead tokens
+>    (`--theme-form-radio-border`, `--theme-form-radio-outline`, both also undeclared anywhere)
+>    fed two further-unused private locals and were removed outright.
+> 2. The `.system`/`.light`/`.dark` `:has(input[value="..."])` selectors and matching
+>    `.option-icon.system/.light/.dark` classes used to say `"auto"` instead of `"system"` — but
+>    the only known consumer, `DisplayThemeSwitch`, has only ever emitted `id`/`value: "system"`
+>    (matching `useSettingsStore`'s `colourScheme` type, which the presentational side has to
+>    track). `"auto"` never matched anything real, so the system option's green gradient marker
+>    had never actually fired. Renamed the selectors to `"system"` rather than the data, since the
+>    data value is a real external contract (`useSettingsStore.setColourScheme` applies it as a
+>    literal CSS class on `<html>` elsewhere in the app) and the selectors are this component's own
+>    presentational-only concern.
+>
+> **`.system`/`.light`/`.dark` selectors**: the component hardcodes these three option *values* as
+> CSS class selectors rather than being value-agnostic — a legacy of its one real consumer,
+> `DisplayThemeSwitch`'s light/dark/system theme picker. All three already shared identical colour
+> values before this migration; only the repeated literal values became tokens here, the selectors
+> themselves are otherwise unchanged (so anything already targeting them by their corrected names
+> keeps working). Making the component genuinely value-agnostic would be a larger, separate change.
+
+Geometry (`--_form-*` sizing locals, `--form-element-*`) is shared/component-internal and untouched
+by this — see `theming-form-geometry-tokens.md` for the shared half.
+
+---
+
+## Global theming — app-level CSS file
+
+```css
+:where(html) {
+  --triple-toggle-switch-surface: var(--rose-09);
+  --triple-toggle-switch-option-ring-focus: var(--rose-04);
+}
+```
+
+---
+
+## Per-instance overrides
+
+```vue
+<TripleToggleSwitchCore
+  v-model="scheme"
+  v-model:field-data="options"
+  style="--triple-toggle-switch-marker-surface: var(--gold-06);"
+/>
+```

package/app/components/05.forms/triple-toggle-switch/TripleToggleSwitchCore.vue

@@ -98,9 +98,16 @@ onMounted(() => {
 <style lang="css">
 @layer components {
 .triple-toggle-switch {
-  --_form-border-colour: var(--theme-form-radio-border);
-
-  --_form-outline-colour: var(--theme-form-radio-outline);
+  /* Public --triple-toggle-switch-* tokens, inline-fallback to the shared --theme-* tokens (see
+     theming-component-token-pattern.md). --_form-border-colour/--_form-outline-colour used to
+     sit here referencing --theme-form-radio-border/-outline — dead tokens, declared nowhere in
+     this layer at all (confirmed by grep), and --_form-border-colour/--_form-outline-colour
+     themselves were never read by any property below either, so removed outright rather than
+     migrated. --_marker-surface replaces the one dead reference that WAS actually read:
+     --_select-scheme-group-background-color used to default from --theme-form-checkbox-bg,
+     equally undeclared anywhere — real (if narrow) bug, since it only rendered visibly when
+     none of the auto/light/dark :has() overrides below matched. */
+  --_marker-surface: var(--triple-toggle-switch-marker-surface, var(--theme-input-surface));
 
   --_form-border-radius: calc(
     (var(--_scheme-icon-font-size) / 2) + var(--form-element-border-width) + var(--form-element-outline-width) +
@@ -111,13 +118,18 @@ onMounted(() => {
   --_form-items-gap: 1rem;
   --_form-padding: 0.6rem;
 
-  --_select-scheme-group-background-color: var(--theme-form-checkbox-bg);
+  --_select-scheme-group-background-color: var(--_marker-surface);
   --_select-scheme-group-background-image: none;
   --_select-scheme-group-padding: 0.5rem;
   --_scheme-icon-font-size: 2rem;
   /* --_scheme-icon-colour: black; */
 
-  &:has(input[value="auto"]:checked) {
+  /* "system" not "auto" — matches useSettingsStore's actual colourScheme value/CSS class
+     ("system" | "dark" | "light"), which DisplayThemeSwitch's real option data uses. Was
+     "auto" here, a name that never matched any real consumer's data, so this gradient never
+     fired in practice (confirmed by grep across the whole layer — nothing anywhere emits value
+     "auto"). Presentational-only rename; the store's own type/class-name contract is untouched. */
+  &:has(input[value="system"]:checked) {
     --_select-scheme-group-background-color: transparent;
     --_select-scheme-group-background-image: radial-gradient(
       circle,
@@ -152,8 +164,8 @@ onMounted(() => {
     grid-template-areas: "select-stack";
     width: fit-content;
 
-    background-color: var(--theme-input-surface);
-    border: var(--form-element-border-width) solid var(--theme-border);
+    background-color: var(--triple-toggle-switch-surface, var(--theme-input-surface));
+    border: var(--form-element-border-width) solid var(--triple-toggle-switch-border, var(--theme-border));
     outline: var(--form-element-outline-width) solid transparent;
     border-radius: 100vw;
     padding: var(--_form-padding);
@@ -161,7 +173,7 @@ onMounted(() => {
     transition: all var(--theme-form-transition-duration) ease-in-out;
 
     &:has(input:focus-visible) {
-      outline: var(--form-element-outline-width) solid var(--theme-ring);
+      outline: var(--form-element-outline-width) solid var(--triple-toggle-switch-ring-focus, var(--theme-ring));
       outline-offset: 0.2rem;
     }
 
@@ -178,7 +190,8 @@ onMounted(() => {
         transition: all v-bind(stepAnimationDuration) ease-in-out;
         background-color: var(--_select-scheme-group-background-color);
         background-image: var(--_select-scheme-group-background-image);
-        border: var(--form-element-border-width) solid light-dark(var(--slate-10), var(--slate-00));
+        border: var(--form-element-border-width) solid
+          var(--triple-toggle-switch-marker-border, light-dark(var(--slate-10), var(--slate-00)));
 
         border-radius: 50%;
 
@@ -211,7 +224,8 @@ onMounted(() => {
         grid-template-areas: "icon-stack";
         place-content: center;
         background: transparent;
-        border: var(--form-element-border-width) solid light-dark(#00000025, #ffffff50);
+        border: var(--form-element-border-width) solid
+          var(--triple-toggle-switch-option-border, light-dark(#00000025, #ffffff50));
         outline: var(--form-element-outline-width) solid transparent;
         border-radius: 50%;
         padding: var(--_select-scheme-group-padding);
@@ -220,39 +234,47 @@ onMounted(() => {
         transition: all calc(var(--theme-form-transition-duration) / 3);
 
         &:has(.option-icon:hover) {
-          outline: var(--form-element-outline-width) solid light-dark(var(--slate-10), var(--slate-00));
+          outline: var(--form-element-outline-width) solid
+            var(--triple-toggle-switch-option-border-hover, light-dark(var(--slate-10), var(--slate-00)));
         }
         &:has(input:focus-visible) {
-          outline: var(--form-element-outline-width) solid var(--theme-ring);
+          outline: var(--form-element-outline-width) solid var(--triple-toggle-switch-option-ring-focus, var(--theme-ring));
           outline-offset: 0.2rem;
         }
 
+        /* .system/.light/.dark all share the exact same colour values today — kept as three
+           selectors (rather than collapsed to one) since DisplayThemeSwitch and any other
+           consumer may already target these class names directly; only the repeated literal
+           values became tokens. This class is bound to each option's `id` in the template
+           (:class="[option.id, ...]"), not a hardcoded literal — "auto" here never matched
+           anything real for the same reason the :has(input[value="auto"]) selector above didn't:
+           the only known consumer's data uses id "system". */
         .option-icon {
           grid-area: icon-stack;
           display: block;
           font-size: var(--_scheme-icon-font-size);
 
-          &.auto {
-            color: light-dark(var(--slate-10), var(--slate-03));
+          &.system {
+            color: var(--triple-toggle-switch-option-icon-color, light-dark(var(--slate-10), var(--slate-03)));
 
             &.active {
-              color: var(--slate-00);
+              color: var(--triple-toggle-switch-option-icon-color-active, var(--slate-00));
             }
           }
 
           &.light {
-            color: light-dark(var(--slate-10), var(--slate-03));
+            color: var(--triple-toggle-switch-option-icon-color, light-dark(var(--slate-10), var(--slate-03)));
 
             &.active {
-              color: var(--slate-00);
+              color: var(--triple-toggle-switch-option-icon-color-active, var(--slate-00));
             }
           }
 
           &.dark {
-            color: light-dark(var(--slate-10), var(--slate-03));
+            color: var(--triple-toggle-switch-option-icon-color, light-dark(var(--slate-10), var(--slate-03)));
 
             &.active {
-              color: var(--slate-00);
+              color: var(--triple-toggle-switch-option-icon-color-active, var(--slate-00));
             }
           }
 
@@ -271,7 +293,7 @@ onMounted(() => {
           }
         }
 
-        /* &:has(input[value="auto"]:checked) {
+        /* &:has(input[value="system"]:checked) {
           --_scheme-icon-colour: white;
         }
 

package/app/components/05.forms/triple-toggle-switch/stories/TripleToggleSwitchCore.stories.ts

@@ -0,0 +1,63 @@
+import type { Meta, StoryFn } from "@nuxtjs/storybook";
+import { ref } from "vue";
+import StorybookComponent from "../TripleToggleSwitchCore.vue";
+import type { IFormMultipleOptions } from "~/types/forms/types.forms.d";
+
+interface TripleToggleSwitchCoreStoryArgs {
+  name: string;
+  stepAnimationDuration: string;
+}
+
+// TripleToggleSwitchCore hardcodes three option *values* as CSS selectors — "system", "light",
+// "dark" — rather than being value-agnostic (see CONSUMER-STYLING.md). This story uses exactly
+// those values so the gradient marker behind each option actually fires; any other value falls
+// back to --triple-toggle-switch-marker-surface with no gradient. DisplayThemeSwitch is the
+// real-world consumer (light/dark/system colour-scheme picker) — this story exercises the bare
+// component the same way, without the store wiring DisplayThemeSwitch adds on top.
+export default {
+  title: "Components/Forms/Triple Toggle Switch/TripleToggleSwitchCore",
+  component: StorybookComponent,
+  argTypes: {
+    name: { control: "text", table: { category: "Basic" } },
+    stepAnimationDuration: {
+      control: "text",
+      description: "CSS transition duration for the marker sliding between options",
+      table: { category: "Styling" },
+    },
+  },
+  args: {
+    name: "colour-scheme",
+    stepAnimationDuration: "250ms",
+  },
+} as Meta<TripleToggleSwitchCoreStoryArgs>;
+
+const Template: StoryFn<TripleToggleSwitchCoreStoryArgs> = (args) => ({
+  components: { StorybookComponent },
+  setup() {
+    const modelValue = ref("system");
+    const fieldData = ref<IFormMultipleOptions>({
+      data: [
+        { id: "system", name: args.name, value: "system", label: "System", icon: "material-symbols:night-sight-auto-sharp" },
+        { id: "light", name: args.name, value: "light", label: "Light", icon: "radix-icons:sun" },
+        { id: "dark", name: args.name, value: "dark", label: "Dark", icon: "radix-icons:moon" },
+      ],
+      total: 3,
+      skip: 0,
+      limit: 3,
+    });
+    return { args, modelValue, fieldData };
+  },
+  template: `
+    <div style="margin: 36px;">
+      <StorybookComponent
+        v-model="modelValue"
+        v-model:field-data="fieldData"
+        :name="args.name"
+        :step-animation-duration="args.stepAnimationDuration"
+      />
+      <div style="margin-top: 1.6rem; font-size: 1.4rem;">Current value: {{ modelValue }}</div>
+    </div>
+  `,
+});
+
+export const Default = Template.bind({});

package/app/components/display-theme-switch/DisplayThemeSwitch.vue

@@ -62,9 +62,13 @@ watch(colorModeVal, (val) => {
 @layer components {
 .colour-scheme-select {
   &.triple-toggle-switch {
-    --_form-border-colour: var(--theme-form-radio-border);
-    --_form-outline-colour: var(--theme-form-radio-outline);
-
+    /* --_form-border-colour/--_form-outline-colour used to sit here referencing
+       --theme-form-radio-border/-outline — dead tokens declared nowhere in the layer, and
+       neither local var was itself ever read by any property below either; removed rather than
+       migrated. --_select-scheme-group-background-color below is repointed at the new public
+       --triple-toggle-switch-marker-surface token instead of the other dead reference it used
+       to carry (--theme-form-checkbox-bg) — see TripleToggleSwitchCore.vue and
+       theming-component-token-pattern.md. */
     --_form-items-gap: 0.4rem;
     --_form-padding: 0.4rem;
     --_select-scheme-group-padding: 0.4rem;
@@ -77,10 +81,13 @@ watch(colorModeVal, (val) => {
       --_scheme-icon-font-size: 1.6rem;
     }
 
-    --_select-scheme-group-background-color: var(--theme-form-checkbox-bg);
+    --_select-scheme-group-background-color: var(--triple-toggle-switch-marker-surface, var(--theme-input-surface));
     --_select-scheme-group-background-image: none;
 
-    &:has(input[value="auto"]:checked) {
+    /* "system", matching sampleFieldData's actual id/value below — was "auto" here, which never
+       matched (this component's own data never used it), so this gradient never fired for the
+       system option in practice. */
+    &:has(input[value="system"]:checked) {
       --_select-scheme-group-background-color: transparent;
       --_select-scheme-group-background-image: radial-gradient(
         circle,
@@ -149,7 +156,7 @@ watch(colorModeVal, (val) => {
           }
 
           .option-icon {
-            &.auto {
+            &.system {
               color: light-dark(var(--slate-10), var(--slate-03));
 
               &.active {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "srcdev-nuxt-components",
   "type": "module",
-  "version": "9.3.12",
+  "version": "9.3.13",
   "main": "nuxt.config.ts",
   "types": "types.d.ts",
   "license": "MIT",