@synopackageland/ui 0.13.0 → 0.13.2

package/docs/theme-hooks.md

@@ -0,0 +1,168 @@
+# Theme hooks: public `data-*` attributes and layout tokens
+
+Since 0.13.1 the attributes and tokens on this page are **public API**. An app
+or a workspace theme may select on them in its own CSS and set the tokens on
+any ancestor. Class names, element nesting and every attribute not listed
+here stay implementation details and can change in any release.
+
+## Stability rules
+
+- A listed attribute keeps its name, the element it sits on and the values
+  listed for it until a **major** release (or a 0.x minor release, which the
+  changelog marks as breaking, as for any other API).
+- New values may be added to an attribute in a patch or minor release. A
+  selector that tests for a value (`[data-variant='primary']`) keeps working; a
+  rule that assumes the listed values are the only ones may not.
+- A token keeps its name and meaning. Its **unset** value is the look the
+  component had before the token existed; changing that default is a visible
+  change and is announced in the changelog.
+- Removing or renaming a listed attribute or token is breaking: it is first
+  deprecated in the changelog for at least one minor release.
+- Select on what is listed, then on standard roles and ARIA states
+  (`[aria-current='page']`, `[aria-expanded]`, `[role='dialog']`). Do not
+  depend on child order, on the tag of an unlisted element or on Tailwind
+  classes.
+
+## Attributes
+
+### Application root and layout
+
+| Attribute | On | Values |
+| --- | --- | --- |
+| `data-ui-app` | `AppRoot`'s root and its floating hosts (portals) | present |
+| `data-ui-theme`, `data-ui-density`, `data-ui-accent` | the app root (mirrored on floating hosts) | theme name, `compact`/`comfortable`, present |
+| `data-ui-presentation` | `AppRoot` root | `mobile`, `window`, `web` |
+| `data-ui-floating` | a floating host (dialog, menu, popover) | present |
+| `data-ui-layout-mode` | `AppLayout` root | `mobile`, `window`, `web` |
+| `data-ui-navigation` | `AppLayout` root, and `AppSidebar`'s `<nav>`, while the navigation is a top bar | `top` (absent for the sidebar and on a phone) |
+| `data-ui-layout-height` | `AppLayout` root | `auto`, `fill` |
+| `data-ui-sidebar-collapsed` | `AppLayout` root and `AppSidebar`'s `<nav>` | `true` while the web rail shows icons only |
+| `data-ui-mobile-open` | `AppLayout` root | `true` while the phone drawer is open |
+| `data-ui-layout-sidebar` | the navigation region (left column, top bar, or phone drawer) | present |
+| `data-ui-layout-main` | the page region beside or under the navigation | present |
+| `data-ui-sidebar-brand` | the brand block (web sidebar, top bar, phone bar, drawer header) | present |
+| `data-ui-brand-icon`, `data-ui-brand-name` | the brand's logo `<img>` and name | present |
+| `data-ui-sidebar-body` | wrapper of the `sidebar` slot | present |
+| `data-ui-sidebar-footer` | wrapper of the `sidebar-footer` slot | present |
+| `data-ui-sidebar-collapse` | the web rail's collapse button | present |
+| `data-ui-mobile-navigation` | the phone bar above the page | present |
+| `data-ui-mobile-menu` | the phone bar's menu (hamburger) button | present |
+| `data-ui-mobile-sidebar-header` | the drawer's header row | present |
+| `data-ui-mobile-backdrop` | the drawer's backdrop | present |
+| `data-ui-app-toolbar` | `AppToolbar` | present |
+| `data-ui-page-header` | `PageHeader` | present |
+| `data-ui-page-header-meta`, `data-ui-page-header-actions` | `PageHeader`'s meta and actions areas | present |
+| `data-page-surface` | `PageContent` | `auto`, `card`, `flat`, `none` |
+
+### Navigation rows (`AppSidebar`, side or top)
+
+| Attribute | On | Values |
+| --- | --- | --- |
+| `data-nav-item` | a row that selects a page | present |
+| `data-nav-branch` | a row with children (expands in the sidebar, opens a menu in the top bar) | present |
+| `data-nav-group-label` | a group title (sidebar only) | present |
+| `data-nav-group` | a group in the top bar, `role="group"` named by its label | present |
+| `data-nav-label`, `data-nav-badge` | a row's label and badge | present |
+| `data-nav-contains-current` | a top-bar branch whose child is the current page | present |
+| `aria-current` | the current page's row | `page` |
+| `data-ui-top-nav-item` | measurable top-level row wrapper | present |
+| `data-ui-overflowed` | row moved into More (hidden and inert in the bar) | `true` |
+| `data-ui-top-nav-more` | More menu trigger | present |
+| `data-ui-selected` | More trigger when its subtree contains the current page | `true` |
+| `data-ui-top-nav-overflow-menu` | portalled More dropdown panel | present |
+| `data-ui-sidebar-user` | `AppSidebarUser` | present |
+| `data-ui-user-avatar`, `data-ui-user-name`, `data-ui-user-detail` | its parts | present |
+
+### Controls and surfaces
+
+| Attribute | On | Values |
+| --- | --- | --- |
+| `data-variant` | `Button` | `primary`, `secondary`, `ghost`, `danger` |
+| `data-variant` | `IconButton` | `primary`, `secondary`, `ghost` |
+| `data-variant` | `SplitButton`'s outer group | `primary`, `secondary` |
+| `data-kind` | `Button` | `tool`, `action` |
+| `data-loading`, `data-disabled` | `Button` | present while loading / explicitly disabled |
+| `data-split-main`, `data-split-arrow` | `SplitButton`'s two halves | present |
+| `data-ui-surface` | `Surface` and every `Card` frame | present |
+| `data-variant` | `Surface` / `Card` frame | `default`, `inset` |
+| `data-ui-dialog`, `data-ui-sheet` | `Dialog` / `Sheet` panels | present |
+| `data-ui-list-item-title`, `-description`, `-meta`, `-actions` | `ListItem` parts | present |
+| `data-ui-statistic-label`, `-value`, `-note` | `Statistic` parts | present |
+
+Select a `Button` variant with its tag so a `Surface`'s `data-variant` is not
+caught as well: `button[data-variant='primary']`.
+
+## Layout and theme tokens
+
+Each token below is read with a fallback: unset, the component looks as it did
+before the token existed. Set them on the app root or any ancestor.
+
+| Token | Affects | Unset |
+| --- | --- | --- |
+| `--ui-nav-row-height` | navigation row height/minimum height; inherited from any ancestor, including outside `AppLayout` | window 42px, web 40px, phone 46px |
+| `--ui-icon-size` | icons in navigation rows (`AppSidebar`, side and top) | 22px in the sidebar, 18px in the top bar |
+| `--ui-heading-weight` | `PageHeader` title, `Card` title, `TypoHeader`, web toolbar titles | 600 (`PageHeader`, `TypoHeader`, toolbar), 700 (`Card`, web `PageHeader`) |
+| `--ui-card-padding` | a regular `Card`'s header, body and footer inset; the body's block padding is 0.8× | 20px (body 16px × 20px). Compact cards are unchanged |
+| `--ui-top-nav-height` | the top navigation bar | `var(--ui-toolbar-height)` |
+| `--ui-top-nav-bg` | the top navigation bar's background | `var(--ui-surface)`; web: `var(--ui-app-web-surface)` |
+| `--ui-top-nav-border` | its bottom rule | `var(--ui-border)`; web: `var(--ui-app-web-border)` |
+| `--ui-mobile-bar-bg` | the phone bar's background | `var(--ui-surface)` |
+| `--ui-mobile-bar-fg` | the phone bar's text, menu button and brand | `var(--ui-text-secondary)` (text), `var(--ui-text)` (button, brand) |
+| `--ui-mobile-bar-border` | the phone bar's bottom rule | `var(--ui-border-subtle)` |
+
+The colour, radius, spacing and web tokens are listed in the
+[README](../README.md#theme-override), [colour system](color-system.md) and
+[adaptive layout](adaptive-layout.md#safe-overrides).
+
+## Example: a dark top bar
+
+```css
+[data-ui-app] {
+  --ui-top-nav-bg: #111827;
+  --ui-top-nav-border: #111827;
+  --ui-mobile-bar-bg: #111827;
+  --ui-mobile-bar-fg: #f9fafb;
+  --ui-icon-size: 20px;
+  --ui-heading-weight: 700;
+  --ui-card-padding: 24px;
+}
+/* Text inside the bar reads on the dark background. */
+[data-ui-app] [data-ui-layout-sidebar] {
+  --ui-text: #f9fafb;
+  --ui-text-muted: #9ca3af;
+  --ui-surface-hover: rgb(255 255 255 / 0.08);
+}
+[data-ui-app] button[data-variant='primary'] {
+  border-radius: 999px;
+}
+```
+
+```vue
+<AppLayout navigation="top" wide-layout="web">
+  <template #sidebar><AppSidebar v-model="page" :groups="groups" /></template>
+  <template #sidebar-footer><AppSidebarUser name="Ada Lin" /></template>
+  <PageContent>…</PageContent>
+</AppLayout>
+```
+
+The Histoire story *DSM 7 / Top navigation and theme hooks* shows both.
+
+## Navigation sizing and overflow
+
+Set `--ui-nav-row-height: 30px` on the app's theme ancestor to override all
+presentations. Layout modes set only the internal `--ui-nav-row-height-default`
+fallback; they never redefine the public token. Existing density presets and
+explicit values on a row or layout still take precedence through normal CSS
+inheritance. Sidebar rows can grow to fit wrapped labels.
+
+With `navigation="top"`, `AppSidebar` measures the available navigation width,
+row widths (including icons and badges), group spacing and More trigger. The
+trailing items move into More in their original order; nested items and disabled
+states are preserved. More is selected when the current page is anywhere in
+its subtree. Tab reaches the trigger, Enter/Space or ArrowDown opens it,
+arrows navigate, and Escape closes it and returns focus. Resizing or changing
+labels/badges remeasures the row. Hidden bar rows are inert and aria-hidden.
+The phone drawer and default sidebar keep their existing behavior.
+
+The portalled panel has `data-ui-top-nav-overflow-menu`; scope panel styles by
+that attribute rather than relying on it being a descendant of the bar.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/ui",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "docs/color-system.md",
     "docs/component-defaults-0.5.7.md",
     "docs/json-ui.md",
-    "docs/layout-rules.md"
+    "docs/layout-rules.md",
+    "docs/theme-hooks.md"
   ],
   "bin": {
     "syno-pkg-land-ui": "./dist/cli.js"