@scalewing/react 1.45.0 → 1.47.0

package/dist/components/nav-items.d.ts

@@ -0,0 +1,21 @@
+/** What a navigation's item is marked by: `aria-current`, or nothing. */
+export type NavItemCurrent = 'page' | 'location' | boolean;
+/** The parts of a navigation item that SectionNav and AppShell validate alike. */
+type CheckedNavItem = {
+    id: string;
+    label: string;
+    count?: number;
+    countLabel?: string;
+};
+/**
+ * `aria-current` for an item: `page`, `location`, `true` for a bare `true`,
+ * and none for `false` or nothing.
+ */
+export declare function navItemAriaCurrent(current: NavItemCurrent | undefined): 'page' | 'location' | 'true' | undefined;
+/**
+ * Fails closed on a navigation's items, named after the component that
+ * draws them: empty or duplicate ids, empty labels, a count that is not a
+ * whole number from 0, and a blank `countLabel` or one without a count.
+ */
+export declare function assertNavItems(component: string, items: readonly CheckedNavItem[]): void;
+export {};

package/dist/components/nav-items.js

@@ -0,0 +1,26 @@
+/**
+ * `aria-current` for an item: `page`, `location`, `true` for a bare `true`,
+ * and none for `false` or nothing.
+ */
+export function navItemAriaCurrent(current) {
+    if (current === true)
+        return 'true';
+    return current || undefined;
+}
+/**
+ * Fails closed on a navigation's items, named after the component that
+ * draws them: empty or duplicate ids, empty labels, a count that is not a
+ * whole number from 0, and a blank `countLabel` or one without a count.
+ */
+export function assertNavItems(component, items) {
+    if (items.some((item) => !item.id.trim() || !item.label.trim()))
+        throw new RangeError(`${component} items need nonempty ids and labels`);
+    if (new Set(items.map((item) => item.id)).size !== items.length)
+        throw new RangeError(`${component} items need unique ids`);
+    if (items.some((item) => item.count !== undefined &&
+        (!Number.isInteger(item.count) || item.count < 0)))
+        throw new RangeError(`${component} item counts are whole numbers from 0`);
+    if (items.some((item) => item.countLabel !== undefined &&
+        (!item.countLabel.trim() || item.count === undefined)))
+        throw new RangeError(`${component} item countLabel is nonempty and comes with a count`);
+}

package/dist/components/select/select-naming.d.ts

@@ -0,0 +1,34 @@
+/**
+ * How a Select is named: by its own `label` (drawn, or visually hidden),
+ * or by words the page already draws, through `aria-labelledby`.
+ */
+export type SelectNaming = {
+    /** The select's own label, drawn above it as Field's. */
+    label: string;
+    /** Keeps the label for assistive technology only, for toolbar chrome. */
+    labelVisuallyHidden?: boolean;
+    'aria-labelledby'?: undefined;
+} | {
+    /**
+     * The id of words the page draws for this choice, such as a heading
+     * or a label beside it: the select draws no label of its own, so
+     * the name is drawn, and read, once.
+     */
+    'aria-labelledby': string;
+    label?: undefined;
+    labelVisuallyHidden?: undefined;
+    /** No mark: the page draws the words, and any mark, itself. */
+    requiredMark?: undefined;
+};
+/**
+ * Fails closed on a Select with no name, or with both: a blank `label`
+ * without `aria-labelledby`, a blank `aria-labelledby`, the two together
+ * (one would silently hide the other), or `requiredMark` with
+ * `aria-labelledby` (there is no label to mark).
+ */
+export declare function assertSelectNaming(naming: {
+    label: unknown;
+    labelVisuallyHidden: unknown;
+    labelledBy: unknown;
+    requiredMark: unknown;
+}): void;

package/dist/components/select/select-naming.js

@@ -0,0 +1,22 @@
+function isBlank(text) {
+    return typeof text !== 'string' || text.trim() === '';
+}
+/**
+ * Fails closed on a Select with no name, or with both: a blank `label`
+ * without `aria-labelledby`, a blank `aria-labelledby`, the two together
+ * (one would silently hide the other), or `requiredMark` with
+ * `aria-labelledby` (there is no label to mark).
+ */
+export function assertSelectNaming(naming) {
+    if (naming.labelledBy === undefined) {
+        if (isBlank(naming.label))
+            throw new RangeError('Select needs a label or aria-labelledby');
+        return;
+    }
+    if (isBlank(naming.labelledBy))
+        throw new RangeError('Select aria-labelledby must be a non-empty id');
+    if (naming.label !== undefined || naming.labelVisuallyHidden !== undefined)
+        throw new RangeError('Select takes label (and labelVisuallyHidden) or aria-labelledby, not both');
+    if (naming.requiredMark !== undefined)
+        throw new RangeError('Select requiredMark needs label: with aria-labelledby the page draws the mark');
+}

package/dist/css/css-app-shell-drawer.d.ts

@@ -0,0 +1,2 @@
+export declare function cssAppShellDrawerClasses(): string;
+export declare function appShellDrawerClassCatalog(): string[];

package/dist/css/css-app-shell-drawer.js

@@ -0,0 +1,91 @@
+import { iconButtonRules } from './css-icon-button.js';
+/* The drawer's width, a named geometry of this frame; a phone keeps a strip of backdrop. */
+const drawerWidth = '20rem';
+const drawer = '.sw-app-shell-drawer';
+/*
+ * AppShell's menu below `lg`: a modal `dialog` on the top layer, docked to
+ * the inline start (the right in right-to-left) at the viewport's full
+ * height on the solid surface, a hairline at its inline end, clearing the
+ * safe areas, a space-8 strip of backdrop left in view on a phone. It
+ * slides in from its edge unless reduced motion is asked for. Its column
+ * is the top row (the close button where the menu button was, then the
+ * header), the nav, which alone scrolls, and the footer. The backdrop is
+ * Dialog's.
+ */
+export function cssAppShellDrawerClasses() {
+    return `${drawer} {
+  background: var(--sw-color-surface);
+  border: 0;
+  border-inline-end: 1px solid var(--sw-color-border);
+  box-sizing: border-box;
+  color: var(--sw-color-text);
+  height: 100%;
+  inset-block: 0;
+  inset-inline: 0 auto;
+  margin: 0;
+  max-height: none;
+  max-width: calc(100% - var(--sw-space-8));
+  overflow: hidden;
+  padding: env(safe-area-inset-top, 0px) 0 env(safe-area-inset-bottom, 0px);
+  padding-inline-start: env(safe-area-inset-left, 0px);
+  width: ${drawerWidth};
+}
+
+${drawer}:dir(rtl) {
+  padding-inline-start: env(safe-area-inset-right, 0px);
+}
+
+${drawer}[open] {
+  animation: sw-app-shell-drawer-in var(--sw-motion-default) var(--sw-motion-easing);
+  display: flex;
+  flex-direction: column;
+}
+
+${drawer}[open]:dir(rtl) {
+  animation-name: sw-app-shell-drawer-in-rtl;
+}
+
+@keyframes sw-app-shell-drawer-in {
+  from { translate: -100% 0; }
+}
+
+@keyframes sw-app-shell-drawer-in-rtl {
+  from { translate: 100% 0; }
+}
+
+${drawer}::backdrop {
+  background: color-mix(in srgb, var(--sw-color-text) 28%, transparent);
+}
+
+.sw-app-shell-drawer-top {
+  align-items: center;
+  display: flex;
+  flex: none;
+  gap: var(--sw-space-2);
+  padding: var(--sw-space-3) var(--sw-space-3) 0;
+}
+
+.sw-app-shell-drawer-top .sw-app-shell-header {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 0;
+}
+
+${iconButtonRules('sw-app-shell-close')}
+
+@media (prefers-reduced-motion: reduce) {
+  ${drawer}[open],
+  ${drawer}[open]:dir(rtl) { animation: none; }
+}
+
+@media (forced-colors: active) {
+  ${drawer} { border-inline-end-color: CanvasText; }
+}`;
+}
+export function appShellDrawerClassCatalog() {
+    return [
+        'sw-app-shell-drawer',
+        'sw-app-shell-drawer-top',
+        'sw-app-shell-close',
+    ];
+}

package/dist/css/css-app-shell-nav.d.ts

@@ -0,0 +1,3 @@
+export declare function cssAppShellNavClasses(): string;
+export declare function cssAppShellRailNavRules(indent: string): string;
+export declare function appShellNavClassCatalog(): string[];

package/dist/css/css-app-shell-nav.js

@@ -0,0 +1,167 @@
+import { typographyVariants } from '@scalewing/tokens';
+import { visuallyHiddenDeclarations } from './css-utilities.js';
+import { coarsePointerQuery, touchTarget } from './touch-target.js';
+const caption = typographyVariants.caption;
+const label = typographyVariants.label;
+/*
+ * The shell's destinations, in the full sidebar and the drawer alike: label
+ * size in the text colour at weight 500, the glyph before the label and the
+ * count pill (the shared rule, `css-count-pill.ts`) at the row's end. The
+ * current one takes the quiet muted fill in the text colour at the label
+ * weight, as SectionNav \`filled\` marks it; hover a lighter fill. Each is
+ * the sm control and the 44 px target on a coarse pointer. A 2 px
+ * transparent border keeps room for forced colours, where the current
+ * link's turns Highlight. A group's label is a muted caption at weight 600
+ * (sentence case, never uppercase). The link rules start at the canvas
+ * (\`[data-theme]\`) to outrank its accent links.
+ */
+export function cssAppShellNavClasses() {
+    return `.sw-app-shell-nav {
+  box-sizing: border-box;
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: var(--sw-space-4);
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: var(--sw-space-2) var(--sw-space-3);
+}
+
+.sw-app-shell-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-1);
+}
+
+.sw-app-shell-group-label {
+  color: var(--sw-color-muted);
+  font-family: var(--sw-font-sans);
+  font-size: ${caption.fontSize}px;
+  font-weight: 600;
+  letter-spacing: ${caption.letterSpacing}px;
+  line-height: ${caption.lineHeight}px;
+  margin: 0;
+  padding-inline: var(--sw-space-2);
+}
+
+.sw-app-shell-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--sw-space-1);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.sw-app-shell-item > .sw-tooltip-anchor {
+  display: flex;
+}
+
+[data-theme] .sw-app-shell-link {
+  align-items: center;
+  border: 2px solid transparent;
+  border-radius: var(--sw-radius-sm);
+  box-sizing: border-box;
+  color: var(--sw-color-text);
+  display: flex;
+  flex: 1 1 auto;
+  font-family: var(--sw-font-sans);
+  font-size: ${label.fontSize}px;
+  font-weight: 500;
+  gap: var(--sw-space-3);
+  letter-spacing: ${label.letterSpacing}px;
+  line-height: ${label.lineHeight}px;
+  min-height: var(--sw-control-sm-min-height);
+  padding: var(--sw-space-1) var(--sw-space-2);
+  text-decoration: none;
+}
+
+[data-theme] .sw-app-shell-link:hover {
+  background: color-mix(in srgb, var(--sw-color-muted) 12%, transparent);
+}
+
+[data-theme] .sw-app-shell-link:focus-visible {
+  outline: var(--sw-focus-ring-width) solid var(--sw-color-accent);
+  outline-offset: calc(-1 * var(--sw-focus-ring-width));
+}
+
+[data-theme] .sw-app-shell-link[aria-current] {
+  background: color-mix(in srgb, var(--sw-color-muted) 18%, transparent);
+  font-weight: ${label.fontWeight};
+}
+
+.sw-app-shell-icon {
+  display: inline-flex;
+  flex: none;
+}
+
+.sw-app-shell-label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+.sw-app-shell-count {
+  flex: none;
+}
+
+@media ${coarsePointerQuery} {
+  [data-theme] .sw-app-shell-link { min-height: ${touchTarget}; }
+}
+
+@media (forced-colors: active) {
+  [data-theme] .sw-app-shell-link { color: LinkText; }
+  [data-theme] .sw-app-shell-link[aria-current] { border-color: Highlight; color: CanvasText; }
+}`;
+}
+/*
+ * The rail (from \`lg\` to 75rem, inside the sidebar's media queries): each
+ * link the 44 px target holding its glyph alone, the label visually hidden
+ * but still its name, the count pill at the link's top end corner. A
+ * group's label is hidden too (it still names its list) and every group
+ * after the first starts under a hairline.
+ */
+export function cssAppShellRailNavRules(indent) {
+    const rules = `.sw-app-shell-sidebar .sw-app-shell-label,
+.sw-app-shell-sidebar .sw-app-shell-group-label { ${visuallyHiddenDeclarations} }
+
+.sw-app-shell-sidebar .sw-app-shell-nav {
+  gap: var(--sw-space-2);
+}
+
+.sw-app-shell-sidebar .sw-app-shell-group + .sw-app-shell-group {
+  border-top: 1px solid var(--sw-color-border);
+  padding-top: var(--sw-space-2);
+}
+
+[data-theme] .sw-app-shell-sidebar .sw-app-shell-link {
+  justify-content: center;
+  min-height: ${touchTarget};
+  padding: 0;
+  position: relative;
+}
+
+.sw-app-shell-sidebar .sw-app-shell-count {
+  inset-block-start: 0;
+  inset-inline-end: 0;
+  position: absolute;
+}`;
+    return rules
+        .split('\n')
+        .map((line) => (line ? `${indent}${line}` : line))
+        .join('\n');
+}
+export function appShellNavClassCatalog() {
+    return [
+        'sw-app-shell-nav',
+        'sw-app-shell-group',
+        'sw-app-shell-group-label',
+        'sw-app-shell-list',
+        'sw-app-shell-item',
+        'sw-app-shell-link',
+        'sw-app-shell-icon',
+        'sw-app-shell-label',
+        // sw-app-shell-count is the shared pill's (css-count-pill.ts).
+    ];
+}

package/dist/css/css-app-shell.d.ts

@@ -0,0 +1,4 @@
+/** From this width up AppShell draws its full sidebar; script reads it too. */
+export declare const appShellWideQuery = "(min-width: 75rem)";
+export declare function cssAppShellClasses(): string;
+export declare function appShellClassCatalog(): string[];

package/dist/css/css-app-shell.js

@@ -0,0 +1,150 @@
+import { breakpointQuery } from './breakpoints.js';
+import { appShellDrawerClassCatalog, cssAppShellDrawerClasses, } from './css-app-shell-drawer.js';
+import { appShellNavClassCatalog, cssAppShellNavClasses, cssAppShellRailNavRules, } from './css-app-shell-nav.js';
+import { iconButtonRules } from './css-icon-button.js';
+/*
+ * The width from which AppShell's sidebar is full rather than a rail: an
+ * internal media query of the component, not a public breakpoint (the
+ * `md` and `lg` tokens stay the only ones products use).
+ */
+const wideShellWidth = 75;
+/** From this width up AppShell draws its full sidebar; script reads it too. */
+export const appShellWideQuery = `(min-width: ${wideShellWidth}rem)`;
+/* The full sidebar's width, a named geometry of this frame. */
+const sidebarWidth = '15rem';
+/* The rail: the 44 px target with a space-3 gutter each side, and its hairline. */
+const railWidth = 'calc(var(--sw-control-md-min-height) + 2 * var(--sw-space-3) + 1px)';
+const fromLg = breakpointQuery('from', 'lg');
+/*
+ * Below `lg`: the page under a sticky top bar (an AppHeader `bar`: the menu
+ * button, the title, the end controls), no sidebar. The frame never makes
+ * `main` a scroll box: the page scrolls with the document.
+ */
+function barRules() {
+    return `.sw-app-shell {
+  min-height: 100vh;
+  min-height: 100dvh;
+}
+
+.sw-app-shell-bar {
+  align-items: center;
+  display: flex;
+  gap: var(--sw-space-2);
+}
+
+.sw-app-shell-bar-title {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.sw-app-shell-bar-end {
+  align-items: center;
+  display: flex;
+  flex: none;
+  gap: var(--sw-space-2);
+}
+
+${iconButtonRules('sw-app-shell-menu')}
+
+.sw-app-shell-main {
+  display: block;
+  min-width: 0;
+}
+
+.sw-app-shell-sidebar,
+.sw-app-shell-sidebar .sw-app-shell-rail-slot {
+  display: none;
+}`;
+}
+/*
+ * From \`lg\`: no bar; the sidebar is a column of the frame's grid, sticky at
+ * the top at the viewport's height on the solid surface with a hairline at
+ * its inline end. Its header and footer keep their height and only the nav
+ * between them scrolls, when it is taller than the window. A rail to 75rem,
+ * full from there.
+ */
+function sidebarRules() {
+    return `@media ${fromLg} {
+  .sw-app-shell {
+    align-items: start;
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
+  }
+
+  .sw-app-shell-bar {
+    display: none;
+  }
+
+  .sw-app-shell-sidebar {
+    background: var(--sw-color-surface);
+    border-inline-end: 1px solid var(--sw-color-border);
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    height: 100vh;
+    height: 100dvh;
+    position: sticky;
+    top: 0;
+    width: ${railWidth};
+  }
+
+  @media not all and ${appShellWideQuery} {
+    .sw-app-shell-sidebar .sw-app-shell-slot {
+      display: none;
+    }
+
+    .sw-app-shell-sidebar .sw-app-shell-rail-slot {
+      display: block;
+    }
+
+${cssAppShellRailNavRules('    ')}
+  }
+}
+
+@media ${appShellWideQuery} {
+  .sw-app-shell-sidebar {
+    width: ${sidebarWidth};
+  }
+}`;
+}
+/*
+ * AppShell: a workspace frame with a pinned side navigation (see
+ * components/AppShell.tsx). The links, groups and the rail's nav are
+ * `css-app-shell-nav.ts`; the menu drawer is `css-app-shell-drawer.ts`.
+ */
+export function cssAppShellClasses() {
+    return `${barRules()}
+
+.sw-app-shell-header,
+.sw-app-shell-footer {
+  flex: none;
+  padding: var(--sw-space-3);
+}
+
+.sw-app-shell-footer {
+  border-top: 1px solid var(--sw-color-border);
+}
+
+${cssAppShellNavClasses()}
+
+${sidebarRules()}
+
+${cssAppShellDrawerClasses()}`;
+}
+export function appShellClassCatalog() {
+    return [
+        'sw-app-shell',
+        'sw-app-shell-bar',
+        'sw-app-shell-menu',
+        'sw-app-shell-bar-title',
+        'sw-app-shell-bar-end',
+        'sw-app-shell-main',
+        'sw-app-shell-sidebar',
+        'sw-app-shell-slot',
+        'sw-app-shell-rail-slot',
+        'sw-app-shell-header',
+        'sw-app-shell-footer',
+        ...appShellNavClassCatalog(),
+        ...appShellDrawerClassCatalog(),
+    ];
+}

package/dist/css/css-button-width.d.ts

@@ -0,0 +1,11 @@
+/**
+ * How wide a Button is: `content` (the default) is as wide as its words;
+ * `full` fills the container's inline size, and in an Inline row takes
+ * the space its siblings leave, such as an Edit beside a ••• menu.
+ */
+export declare const buttonWidths: readonly ["content", "full"];
+export type ButtonWidth = (typeof buttonWidths)[number];
+/** The class a width adds; `content` adds none (`cx` drops `undefined`). */
+export declare function buttonWidthClass(width: ButtonWidth): string | undefined;
+export declare function cssButtonWidthClasses(): string;
+export declare function buttonWidthClassCatalog(): string[];

package/dist/css/css-button-width.js

@@ -0,0 +1,36 @@
+/**
+ * How wide a Button is: `content` (the default) is as wide as its words;
+ * `full` fills the container's inline size, and in an Inline row takes
+ * the space its siblings leave, such as an Edit beside a ••• menu.
+ */
+export const buttonWidths = ['content', 'full'];
+const full = 'sw-button-full';
+/** The class a width adds; `content` adds none (`cx` drops `undefined`). */
+export function buttonWidthClass(width) {
+    return width === 'full' ? full : undefined;
+}
+/*
+ * A full button fills a Stack, a Grid cell or any column. As a direct
+ * child of an Inline row it shares the row with its siblings, which keep
+ * their own width (a ••• or a second button), as a full Select does; in a
+ * wrapping row it grows from its words' width instead, so it moves to a
+ * line of its own rather than shrinking past them. Its words stay centred.
+ */
+export function cssButtonWidthClasses() {
+    return `.${full} {
+  width: 100%;
+}
+
+.sw-inline > .${full} {
+  flex: 1 1 0;
+  min-width: 0;
+}
+
+.sw-inline.sw-wrap > .${full} {
+  flex: 1 1 auto;
+  width: auto;
+}`;
+}
+export function buttonWidthClassCatalog() {
+    return [full];
+}

package/dist/css/css-button.js

@@ -1,6 +1,7 @@
 import { buttonSizes, buttonVariants, controlScale, typographyVariants, } from '@scalewing/tokens';
 import { breakpointQuery } from './breakpoints.js';
 import { buttonGroupAttachedClassCatalog, cssButtonGroupAttachedClasses, } from './css-button-group-attached.js';
+import { buttonWidthClassCatalog, cssButtonWidthClasses, } from './css-button-width.js';
 import { quietFill } from './quiet-fill.js';
 const label = typographyVariants.label;
 /**
@@ -135,6 +136,7 @@ ${disabledNeutralRules()}
 ${pressedRules()}
 ${ariaDisabledForcedRules()}
 ${sizeRules()}
+${cssButtonWidthClasses()}
 ${groupRules()}
 
 ${cssButtonGroupAttachedClasses()}`;
@@ -162,6 +164,7 @@ export function buttonClassCatalog() {
         ...webButtonVariants.map((variant) => `sw-button-${variant}`),
         'sw-button-disabled-neutral',
         ...buttonSizes.map((size) => `sw-button-${size}`),
+        ...buttonWidthClassCatalog(),
         'sw-button-group',
         ...buttonGroupJustifies.map((name) => `sw-button-group-${name}`),
         ...buttonGroupAttachedClassCatalog(),

package/dist/css/css-components.js

@@ -21,6 +21,7 @@ import { cssCheckboxClasses } from './css-checkbox.js';
 import { cssRadioGroupClasses } from './css-radio-group.js';
 import { cssChromeClasses } from './css-chrome.js';
 import { cssSectionNavClasses } from './css-section-nav.js';
+import { cssAppShellClasses } from './css-app-shell.js';
 import { cssDataClasses } from './css-data.js';
 import { cssSegmentedClasses } from './css-segmented.js';
 import { cssTableClasses } from './css-table.js';
@@ -185,6 +186,8 @@ ${cssChromeClasses()}
 
 ${cssSectionNavClasses()}
 
+${cssAppShellClasses()}
+
 ${cssDialogClasses()}
 
 ${cssDialogFrameClasses()}

package/dist/css/css-count-pill.d.ts

@@ -1,2 +1,9 @@
+/** The pills that take a tone modifier: NavCount's and AppShell's item count. */
+declare const tonedPills: readonly ["sw-nav-count", "sw-app-shell-count"];
+/** The tones other than the pill's own danger. */
+declare const pillTones: readonly ["accent", "warning"];
+/** A toned pill's modifier class, such as `sw-nav-count-warning`. */
+export declare function countToneClass(pill: (typeof tonedPills)[number], tone: (typeof pillTones)[number]): string;
 export declare function cssCountPillClasses(): string;
 export declare function countPillClassCatalog(): string[];
+export {};