@xleddyl/443-components-vue 0.8.5 → 0.9.1

package/README.md

@@ -100,10 +100,27 @@ Vite 8 minifies CSS with Lightning CSS. Set `build.cssTarget` to browsers that s
 
 ## Theming
 
-Tokens live on `.k-root`, never on `:root`. Override them on a root element: Root props, inline style or host CSS.
+Tokens live on `.k-root`, never on `:root`. Override them on a root element: host CSS, Root props or inline style.
+
+The brand of an app is a custom theme: a class on the outermost root, with the token overrides in host CSS. Keep the brand values in this one place, not in Root props.
+
+```vue
+<KRoot class="theme-acme">...</KRoot>
+```
+
+```css
+.k-root.theme-acme {
+   --k-accent: #ff4d00;
+   --k-accent-contrast: #ffffff;
+   --k-font-sans: 'Inter', sans-serif;
+   --k-radius-scale: 0.75;
+}
+```
+
+Use Root props for values that change at runtime (an accent that the user selects, a preview, a demo):
 
 ```vue
-<KRoot accent="#ff4d00" font-sans="'Inter', sans-serif" :radius-scale="0.75" theme="dark">
+<KRoot :accent="userAccent" theme="dark">
 ```
 
 Input tokens, declared only on the outermost root so nested roots inherit them: `--k-accent`, `--k-accent-contrast`, `--k-font-sans`, `--k-font-mono`, `--k-font-size`, `--k-font-features`, `--k-line-height`, `--k-radius-scale`. Every other token (surfaces, text, lines, accent shades, status colors, radii, shadows, motion) is derived per root, so a nested root with its own `theme` or `accent` re-themes a region. The full list is in [CONVENTIONS.md](./CONVENTIONS.md#tokens).
@@ -169,14 +186,10 @@ import '@fontsource-variable/funnel-display'
 import '@fontsource-variable/geist-mono'
 ```
 
-Presets set the input tokens (accent, accent contrast and accent text, fonts, font features, radius scale) and the surface, line and text tokens. Root props, inline style and unlayered host CSS still win, so a custom brand is a few lines:
-
-```vue
-<KRoot accent="#ff4d00" accent-contrast="#ffffff" :radius-scale="0.5" theme="dark">...</KRoot>
-```
+Presets set the input tokens (accent, accent contrast and accent text, fonts, font features, radius scale) and the surface, line and text tokens. Unlayered host CSS, Root props and inline style still win, so a custom theme on top of a preset is a few lines of host CSS (see [Theming](#theming)):
 
 ```css
-.k-root.brand-secret {
+.k-root.theme-acme {
    --k-accent: #ff4d00;
    --k-radius-scale: 0.5;
 }
@@ -184,6 +197,8 @@ Presets set the input tokens (accent, accent contrast and accent text, fonts, fo
 
 Semantic color props are always called `tone` and accept `'neutral' | 'accent' | 'info' | 'success' | 'warning' | 'danger'` (type `Tone`).
 
+Buttons show `icon` before the label and `trailingIcon` after it. Put action icons (`plus`, `trash`, `pencil`) in `icon`. Put direction icons (`arrow-right`, `chevron-right`, `arrow-top-right-on-square`) in `trailingIcon`: `<KButton trailing-icon="arrow-right">Continue</KButton>`.
+
 ## Scoping
 
 - The reset only matches `.k-root` and its descendants, wrapped in `:where()` (zero specificity). Markup outside a root keeps browser defaults.
@@ -452,7 +467,7 @@ Ready defaults to start a dashboard project: an app frame, an auth frame and pag
 | `breadcrumbs`                                                                      |                                 | Rendered in the desktop topbar. `#topbar` replaces them, `#actions` adds buttons on the right.                                                                                                                                                                                                                                                             |
 | `search`                                                                           | `false`                         | `true` adds a CommandPalette with every navigation item, an array adds your own command groups, an async function `(query, signal) => CommandGroup<T>[]` searches on your server (item `data` reaches `#search-item` typed) (matching navigation items come first unless `searchNavigation` is `false`). `#search` replaces it.                            |
 | `searchProps`                                                                      |                                 | Options for the built-in CommandPalette: `minQueryLength`, `debounce`, `placeholder`, `label`, `emptyText` (a string or `(query) => string`), `minQueryText`, `errorText`, `loadingText`, `resultsText`, `notice`, `recentKey`, footer labels. Slots `#search-item`, `#search-empty`, `#search-group-label` and `#search-after-results` reach the palette. |
-| `themeSwitch`                                                                      | `'sidebar'`                     | `'sidebar'`, `'topbar'` or `false`.                                                                                                                                                                                                                                                                                                                        |
+| `themeSwitch`                                                                      | `false`                         | `'sidebar'`, `'topbar'` or `false`. The default keeps the theme choice only in the Appearance section of the settings modal. With `accountAction="menu"` there is no settings modal, so set `'sidebar'` or `'topbar'`.                                                                                                                                     |
 | `collapsible`, `v-model:collapsed`, `storageKey`                                   | `true`, `'k-sidebar-collapsed'` | Icon rail on desktop. Persisted in a cookie under Nuxt (rendered on the server, no flash) or `localStorage` elsewhere. `false` disables persistence.                                                                                                                                                                                                       |
 | `shortcut`                                                                         | `'mod+b'`                       | Toggles the rail on desktop and the drawer on mobile. `searchShortcut` defaults to `mod+k`.                                                                                                                                                                                                                                                                |
 | `v-model:open`                                                                     | `false`                         | Mobile drawer (below 768px of shell width): scrim, focus moves into the drawer, the content is `inert`, Escape and the scrim close it and focus returns to the burger.                                                                                                                                                                                     |
@@ -494,6 +509,7 @@ A large dialog (60rem) with a section nav on the left and the content on the rig
 - Built-in sections, used when no `#section-<id>` slot fills them: `account` (profile card, your `#account-fields`, a sign out button) and `appearance` (`AppearanceSettings`: theme cards light, dark, system and preset cards; `presets` limits or hides them).
 - `@sign-out` adds a Sign out item at the bottom of the nav and in the account section.
 - Labels: `title` (accessible name of the dialog, default `Settings`), `closeLabel`, `navLabel`, `signOutLabel`, `accountLabel`, `accountText`, `appearanceLabel`, `appearanceText`, `sessionLabel`, `sessionText`, `themeLabel`, `themeText`, `presetLabel`, `presetText`.
+- Subpages: `#section-<id>` and `#actions-<id>` get `page`, `pages`, `openPage({ id, label, description? })` and `back()`. With a page open, the header shows a breadcrumb from the section to the page, and the title and description of the page; a click on a breadcrumb goes back to it. `v-model:pages` binds the stack (it also works unbound). Changing section clears it. Render the detail when `page` is set, the list otherwise.
 - `hide-session` hides the Session group (sign out) in the account section; the Sign out item in the nav stays. `beforeClose` works as on Modal.
 - Accessibility: native modal `<dialog>` (focus trap, Escape, focus returns to the trigger), the nav is a labelled `nav` of buttons with `aria-current` and `aria-controls`, the content is a `section` labelled by its heading.
 
@@ -589,7 +605,7 @@ export default defineAppConfig({
          ],
          signOutTo: '/logout',
       },
-      dashboard: { variant: 'inset', search: true, themeSwitch: 'sidebar' },
+      dashboard: { variant: 'inset', search: true },
       auth: { variant: 'split', footer: 'Acme Inc.', asideTitle: 'Run the store.' },
    },
 })

package/dist/components/templates/DashboardLayout.vue

@@ -189,7 +189,7 @@ const props = defineProps({
   searchPlaceholder: { type: String, required: false },
   searchShortcut: { type: [String, Boolean], required: false, default: "mod+k" },
   searchNavigationLabel: { type: String, required: false },
-  themeSwitch: { type: [String, Boolean], required: false, default: "sidebar" },
+  themeSwitch: { type: [String, Boolean], required: false, default: false },
   collapsible: { type: Boolean, required: false, default: true },
   storageKey: { type: [String, Boolean], required: false, default: "k-sidebar-collapsed" },
   shortcut: { type: [String, Boolean], required: false, default: "mod+b" },

package/dist/components/templates/SettingsModal.vue

@@ -98,15 +98,20 @@
             >
                <header class="k-settings-modal-header">
                   <div class="k-settings-modal-heading">
+                     <Breadcrumbs
+                        v-if="currentPage"
+                        class="k-settings-modal-breadcrumbs"
+                        :items="breadcrumbItems"
+                     />
                      <h2 :id="`${baseId}-title`" class="k-settings-modal-title">
-                        {{ active.label }}
+                        {{ currentPage?.label ?? active.label }}
                      </h2>
-                     <p v-if="active.description" class="k-settings-modal-description">
-                        {{ active.description }}
+                     <p v-if="headingDescription" class="k-settings-modal-description">
+                        {{ headingDescription }}
                      </p>
                   </div>
                   <div v-if="$slots[`actions-${active.id}`]" class="k-settings-modal-actions">
-                     <slot :name="`actions-${active.id}`" :section="active" :close="close" />
+                     <slot :name="`actions-${active.id}`" v-bind="slotProps(active, close)" />
                   </div>
                </header>
                <div
@@ -117,7 +122,7 @@
   'is-overflow-bottom': contentEdges.overflowBottom.value
 }"
                >
-                  <slot :name="`section-${active.id}`" :section="active" :close="close">
+                  <slot :name="`section-${active.id}`" v-bind="slotProps(active, close)">
                      <template v-if="active.id === 'account' && account">
                         <div class="k-settings-modal-account">
                            <Avatar
@@ -171,7 +176,7 @@
 </template>
 
 <script setup>
-import { computed, useId, useTemplateRef } from "vue";
+import { computed, useId, useTemplateRef, watch } from "vue";
 import { THEME_PRESETS } from "../../composables/usePreset";
 import { useLocale } from "../../composables/useLocale";
 import { useLinkResolver } from "../../internal/core/link";
@@ -181,6 +186,7 @@ import Icon from "../core/Icon.vue";
 import Avatar from "../data/Avatar.vue";
 import Badge from "../data/Badge.vue";
 import Modal from "../overlays/Modal.vue";
+import Breadcrumbs from "../layout/Breadcrumbs.vue";
 import AppearanceSettings from "./AppearanceSettings.vue";
 import SettingsGroup from "./SettingsGroup.vue";
 const props = defineProps({
@@ -209,6 +215,7 @@ defineSlots();
 const emit = defineEmits(["open", "close", "afterLeave"]);
 const open = defineModel("open", { type: Boolean, ...{ default: false } });
 const section = defineModel("section", { type: String });
+const pages = defineModel("pages", { type: Array, ...{ default: () => [] } });
 const { t } = useLocale();
 const titleText = computed(() => props.title ?? t("settings.title"));
 const closeText = computed(() => props.closeLabel ?? t("settings.close"));
@@ -259,6 +266,34 @@ const activeId = computed(() => {
   return selectable.value[0]?.id;
 });
 const active = computed(() => sectionList.value.find((item) => item.id === activeId.value));
+const currentPage = computed(() => pages.value.at(-1));
+const headingDescription = computed(
+  () => currentPage.value ? currentPage.value.description : active.value?.description
+);
+function goTo(depth) {
+  pages.value = pages.value.slice(0, depth);
+}
+function openPage(page) {
+  pages.value = [...pages.value, page];
+}
+function back() {
+  goTo(pages.value.length - 1);
+}
+const breadcrumbItems = computed(() => [
+  { label: active.value?.label ?? "", onClick: () => goTo(0) },
+  ...pages.value.map((page, index) => ({
+    label: page.label,
+    onClick: index < pages.value.length - 1 ? () => goTo(index + 1) : void 0
+  }))
+]);
+function slotProps(item, close) {
+  return { section: item, close, page: currentPage.value, pages: pages.value, openPage, back };
+}
+watch(activeId, () => goTo(0));
+watch(
+  () => pages.value.length,
+  () => contentBody.value?.scrollTo({ top: 0 })
+);
 function select(id) {
   section.value = id;
 }

package/dist/components/templates/SettingsModal.vue.d.ts

@@ -1,6 +1,6 @@
 import type { ThemePreset } from '../../composables/usePreset';
 import type { DialogBeforeClose } from '../overlays/types';
-import type { SettingsModalAccount, SettingsModalSection, SettingsSectionSlotProps } from './types';
+import type { SettingsModalAccount, SettingsModalPage, SettingsModalSection, SettingsSectionSlotProps } from './types';
 type __VLS_Slots = {
     'account-fields'?: (props: {
         account: SettingsModalAccount;
@@ -33,6 +33,7 @@ declare const __VLS_base: import("vue").DefineComponent<{
     beforeClose?: DialogBeforeClose;
     open?: boolean | undefined;
     section?: string;
+    pages?: SettingsModalPage[];
     key?: PropertyKey | undefined;
     loading?: boolean;
     prefix?: "k-modal" | "k-drawer" | undefined;
@@ -249,6 +250,7 @@ declare const __VLS_base: import("vue").DefineComponent<{
     "update:open": (value: boolean) => any;
     afterLeave: () => any;
     "update:section": (value: string | undefined) => any;
+    "update:pages": (value: SettingsModalPage[]) => any;
 }, string, import("vue").PublicProps, Readonly<{
     sections?: SettingsModalSection[];
     account?: SettingsModalAccount;
@@ -272,6 +274,7 @@ declare const __VLS_base: import("vue").DefineComponent<{
     beforeClose?: DialogBeforeClose;
     open?: boolean | undefined;
     section?: string;
+    pages?: SettingsModalPage[];
     key?: PropertyKey | undefined;
     loading?: boolean;
     prefix?: "k-modal" | "k-drawer" | undefined;
@@ -488,6 +491,7 @@ declare const __VLS_base: import("vue").DefineComponent<{
     "onUpdate:open"?: ((value: boolean) => any) | undefined;
     onAfterLeave?: (() => any) | undefined;
     "onUpdate:section"?: ((value: string | undefined) => any) | undefined;
+    "onUpdate:pages"?: ((value: SettingsModalPage[]) => any) | undefined;
 }>, {
     sections: SettingsModalSection[];
     presets: false | readonly ThemePreset[];

package/dist/components/templates/types.d.ts

@@ -30,9 +30,18 @@ export interface SettingsModalSection {
     badge?: string | number;
     disabled?: boolean;
 }
+export interface SettingsModalPage {
+    id: string;
+    label: string;
+    description?: string;
+}
 export interface SettingsSectionSlotProps {
     section: SettingsModalSection;
     close: () => void;
+    page: SettingsModalPage | undefined;
+    pages: SettingsModalPage[];
+    openPage: (page: SettingsModalPage) => void;
+    back: () => void;
 }
 export interface SettingsModalAccount {
     name: string;

package/dist/styles/layout/app-shell.css

@@ -203,6 +203,49 @@ html.k-root body {
       transform: rotate(180deg);
    }
 
+   @media (hover: hover) {
+      .k-shell.is-collapsed .k-sidebar-header:has(> .k-sidebar-brand:not(:empty)) {
+         position: relative;
+      }
+
+      .k-shell.is-collapsed
+         .k-sidebar-header:has(> .k-sidebar-brand:not(:empty))
+         > .k-sidebar-brand,
+      .k-shell.is-collapsed
+         .k-sidebar-header:has(> .k-sidebar-brand:not(:empty))
+         > .k-sidebar-collapse {
+         transition: opacity var(--k-duration) var(--k-ease);
+      }
+
+      .k-shell.is-collapsed
+         .k-sidebar-header:has(> .k-sidebar-brand:not(:empty))
+         > .k-sidebar-collapse {
+         position: absolute;
+         top: 50%;
+         left: 50%;
+         translate: -50% -50%;
+         opacity: 0;
+      }
+
+      .k-shell.is-collapsed
+         .k-sidebar-header:has(> .k-sidebar-brand:not(:empty)):is(
+            :hover,
+            :has(> .k-sidebar-collapse:focus-visible)
+         )
+         > .k-sidebar-brand {
+         opacity: 0;
+      }
+
+      .k-shell.is-collapsed
+         .k-sidebar-header:has(> .k-sidebar-brand:not(:empty)):is(
+            :hover,
+            :has(> .k-sidebar-collapse:focus-visible)
+         )
+         > .k-sidebar-collapse {
+         opacity: 1;
+      }
+   }
+
    .k-shell.is-collapsed .k-navlink {
       justify-content: center;
       padding-inline: 0;

package/dist/styles/overlays/command.css

@@ -13,7 +13,7 @@
    border: 1px solid var(--k-field-line);
    border-radius: var(--k-radius-md);
    box-shadow: var(--k-shadow-xs);
-   cursor: text;
+   cursor: pointer;
    transition:
       border-color var(--k-duration) var(--k-ease),
       color var(--k-duration) var(--k-ease),

package/dist/styles/templates/dashboard-layout.css

@@ -55,7 +55,30 @@
 @container k-shell (min-width: 768px) {
    .k-shell.is-collapsed .k-dashboard-search.k-command-trigger {
       justify-content: center;
+      min-width: 0;
+      height: 1.875rem;
       padding: 0;
+      color: var(--k-text-dimmed);
+      background: transparent;
+      border-color: transparent;
+      box-shadow: none;
+      transition:
+         background-color var(--k-duration) var(--k-ease),
+         color var(--k-duration) var(--k-ease),
+         scale var(--k-duration) var(--k-ease);
+   }
+
+   .k-shell.is-collapsed .k-dashboard-search.k-command-trigger:hover {
+      color: var(--k-text-muted);
+      background: var(--k-hover);
+   }
+
+   .k-shell.is-collapsed .k-dashboard-search.k-command-trigger:active {
+      scale: 0.985;
+   }
+
+   .k-shell.is-collapsed .k-dashboard-search.k-command-trigger:focus-visible {
+      box-shadow: var(--k-focus-ring);
    }
 
    .k-shell.is-collapsed .k-dashboard-search .k-command-trigger-text,

package/dist/styles/templates/settings-modal.css

@@ -161,6 +161,10 @@
    min-width: 0;
 }
 
+.k-settings-modal-breadcrumbs {
+   margin-bottom: 0.25rem;
+}
+
 .k-settings-modal-title {
    font-size: 0.9375rem;
    font-weight: var(--k-font-weight-strong, 600);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xleddyl/443-components-vue",
-  "version": "0.8.5",
+  "version": "0.9.1",
   "description": "Compact, scoped dashboard components for Vue and Nuxt",
   "license": "MIT",
   "author": "Edoardo Alberti (https://github.com/xleddyl)",