@nubisco/ui 5.6.0 → 5.8.0

package/src/styles/_theme.scss

@@ -1,5 +1,6 @@
 @use 'sass:color';
 @use 'sass:map';
+@use 'accent';
 @use 'config';
 @use 'variables/layout';
 @use 'variables/colors';
@@ -158,11 +159,7 @@
     // hover border visibly moves. The dark theme repeats the mix at 50%
     // because its --nb-c-primary is already a lighter step of the same ramp
     // and needs less white to land on the same wash (dE2000 0.00 there).
-    --nb-c-primary-subtle: color-mix(
-      in srgb,
-      var(--nb-c-primary) 39%,
-      var(--nb-c-white)
-    );
+    @include accent.subtle(39%);
 
     --nb-c-secondary: var(--nb-c-plain-black-700);
     --nb-c-secondary-a11y: var(--nb-c-plain-black-700-a11y);
@@ -375,7 +372,7 @@
     --nb-c-component-discrete-text: var(--nb-c-nouveau-gray-700);
 
     // Focus ring — used by all interactive controls via :focus-visible
-    --nb-c-focus-ring: var(--nb-c-primary);
+    @include accent.focus-ring;
 
     // ── Scrim / overlay ───────────────────────────────────────────────────
     // The dim laid over the page by anything that takes over the viewport:
@@ -588,11 +585,7 @@
     // Dark chrome derived from the brand: a near-black tint of --nb-c-primary so
     // rebranding the primary colour re-tints the sidebar too (semantic, not a
     // raw palette tint).
-    --nb-shell-sidebar-bg: color-mix(
-      in srgb,
-      var(--nb-c-primary) 20%,
-      var(--nb-c-black)
-    );
+    @include accent.shell;
     --nb-shell-sidebar-width: calc(var(--nb-base-unit) * 7); // 56px
     // The verbose variant's rail width. A token rather than a literal inside
     // Shell.vue's variant rule, so a product with long navigation labels can
@@ -613,19 +606,6 @@
       var(--nb-c-white) 90%,
       transparent
     );
-    --nb-shell-sidebar-link-active-bg: color-mix(
-      in srgb,
-      var(--nb-c-primary) 25%,
-      transparent
-    );
-    // Light tint of --nb-c-primary: keeps the accent on-brand and rebrandable
-    // while staying legible (~6:1) on the dark rail, where --nb-c-primary itself
-    // is too dark (~2.5:1).
-    --nb-shell-sidebar-link-active-color: color-mix(
-      in srgb,
-      var(--nb-c-primary) 60%,
-      var(--nb-c-white)
-    );
     --nb-shell-topbar-height: calc(var(--nb-base-unit) * 6.25); // 50px
 
     // Shell chrome. Every rule that paints the frame reads one of these, so a
@@ -672,10 +652,6 @@
     --nb-shell-inspector-max-width: max(calc(var(--nb-base-unit) * 36), 50vw);
     --nb-shell-inspector-border: 1px solid var(--nb-c-border);
     --nb-shell-inspector-bg: var(--nb-c-surface);
-    // The grab-line on the inspector's resize handle. A token, not a literal
-    // brand hex: a white-label product should never have to name the vendor's
-    // ramp to restyle the frame.
-    --nb-shell-inspector-resize-color: var(--nb-c-primary);
     // The dimmer behind the navigation drawer at collapsed widths. Black at
     // 45% reads on both themes because it darkens whatever is under it rather
     // than painting a colour of its own.
@@ -707,11 +683,7 @@
     --nb-c-primary: #{colors.get-color('grape-hyacinth', 400)};
     // Same wash, re-mixed: the dark --nb-c-primary is a 400, so it takes less
     // white than the light 500 does to reach the tint this token used to alias.
-    --nb-c-primary-subtle: color-mix(
-      in srgb,
-      var(--nb-c-primary) 50%,
-      var(--nb-c-white)
-    );
+    @include accent.subtle(50%);
     --nb-c-primary-a11y: #{colors.color-contrast(
         colors.get-color('grape-hyacinth', 400)
       )};

package/src/styles/variables/_categories.scss

@@ -0,0 +1,169 @@
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use '../logic/a11y' as a11y;
+@use 'layers';
+
+/// The audience categories, and the accent pair each one resolves to.
+///
+/// Nubisco groups its products by audience: creatives, engineers, home, fun.
+/// These are the four accents that grouping resolves to, each a
+/// `(light, dark)` pair.
+///
+/// ## What is deliberately not here
+///
+/// There is no product list. The library holds the four values and nothing
+/// else: it does not know which product belongs to which category, and it must
+/// not. A registry of product ids here would mean cutting a library release
+/// every time a product is added or renamed, and it would invert the
+/// dependency, making the design system know about the things that consume it.
+/// An app names its own category when it themes itself, so a new product needs
+/// no change to this file. The product-to-category map is a portfolio fact and
+/// lives in the workspace standards.
+///
+/// ## Why these exact values
+///
+/// Every value clears WCAG AA (4.5:1) against all four surface layers of the
+/// mode it belongs to. That is a stricter bar than measuring against pure
+/// white and pure black, and it is the one that matters: the library never
+/// renders a pure-white surface. Light accents are measured against the
+/// darkest light layer (`layer-2`, `#e7e8e9`) and dark accents against the
+/// lightest dark layer (`layer-3`, `#3d3e3f`), because those are the worst
+/// cases. `tests/categoryContrast.test.ts` measures the compiled values and
+/// fails if an edit drops one below the bar.
+///
+/// Hover and active are the adjacent steps of the same ramp, darker in light
+/// mode and lighter in dark, so both are strictly further from the surface
+/// than the base. The base is therefore the worst case, and testing it is
+/// enough.
+///
+/// @type Map
+/// @access public
+/// @group @nubisco/colors
+$categories: (
+  creatives: (
+    #846201,
+    #e8c15a,
+  ),
+  engineers: (
+    #5b48c9,
+    #a99dff,
+  ),
+  home: (
+    #086f9e,
+    #5ec1e8,
+  ),
+  fun: (
+    #b83266,
+    #f686ae,
+  ),
+);
+
+/// The `(light, dark)` accent pair for a category.
+///
+/// An unknown name is a build error rather than a silent fallback: a typo that
+/// quietly resolved to the default accent would ship a product in the wrong
+/// colour and nothing would say so.
+///
+/// @param {String} $name - a key of `$categories`
+/// @return {List} the `(light, dark)` pair
+/// @access public
+/// @group @nubisco/colors
+@function category($name) {
+  @if not map.has-key($categories, $name) {
+    @error "Unknown category #{$name}. Expected one of: #{map.keys($categories)}.";
+  }
+  @return map.get($categories, $name);
+}
+
+/// Validates a `(light, dark)` accent pair supplied by an app.
+///
+/// An app with an established identity of its own passes its own pair rather
+/// than taking its category's. This checks the shape so a malformed value
+/// fails at build time instead of emitting nonsense custom properties.
+///
+/// @param {List} $accent - a two-item list of colours
+/// @return {List} the same pair, once validated
+/// @access public
+/// @group @nubisco/colors
+@function accent-pair($accent) {
+  @if meta.type-of($accent) != list or list.length($accent) != 2 {
+    @error "An accent must be a (light, dark) pair of colours, got #{$accent}.";
+  }
+  @each $value in $accent {
+    @if meta.type-of($value) != color {
+      @error "An accent pair must hold colours, got #{$value}.";
+    }
+  }
+  @return $accent;
+}
+
+/// The surfaces an accent is measured against, per mode.
+///
+/// These are the library's own layers, resolved from
+/// `variables/_layers.scss`, not pure white and pure black. That distinction
+/// is the point: an accent verified against a surface the product never
+/// renders has not been verified. The worst case is the darkest light layer
+/// and the lightest dark layer, and both are in here.
+///
+/// @type Map
+/// @access private
+/// @group @nubisco/colors
+/// Read from the layer ramps rather than restated, so a change to the surface
+/// system is measured against automatically instead of silently invalidating
+/// numbers copied out of it.
+$_grounds: (
+  light: (
+    layers.level(layers.$light, surface, 0),
+    layers.level(layers.$light, surface, 1),
+    layers.level(layers.$light, surface, 2),
+    layers.level(layers.$light, surface, 3),
+  ),
+  dark: (
+    layers.level(layers.$dark, surface, 0),
+    layers.level(layers.$dark, surface, 1),
+    layers.level(layers.$dark, surface, 2),
+    layers.level(layers.$dark, surface, 3),
+  ),
+);
+
+/// Fails the build if an accent pair does not clear WCAG AA on every surface.
+///
+/// The library measures the accents it ships, in
+/// `tests/categoryContrast.test.ts`. It cannot measure an accent an app
+/// supplies, because it never sees it. An app that overrides its accent calls
+/// this so its own build holds it to the same bar.
+///
+/// ```scss
+/// @debug nb.assert-accent-contrast((#0b7285, #41d6e0));
+/// ```
+///
+/// @param {List} $accent - a `(light, dark)` pair
+/// @param {Number} $minimum - the ratio to clear, 4.5 by default
+/// @return {String} a summary, so the call reads as an assertion that returns
+/// @access public
+/// @group @nubisco/colors
+@function assert-accent-contrast($accent, $minimum: 4.5) {
+  $pair: accent-pair($accent);
+  $worst: 21;
+
+  @each $mode, $grounds in $_grounds {
+    $value: list.nth($pair, 2);
+    $direction: 'lighter';
+    @if $mode == light {
+      $value: list.nth($pair, 1);
+      $direction: 'darker';
+    }
+    @each $ground in $grounds {
+      $ratio: a11y.contrast-ratio($value, $ground);
+      @if $ratio < $minimum {
+        @error "Accent #{$value} is #{$ratio}:1 on #{$mode} surface #{$ground}, below #{$minimum}:1. Pick a #{$direction} value.";
+      }
+      @if $ratio < $worst {
+        $worst: $ratio;
+      }
+    }
+  }
+
+  @return 'accent clears #{$minimum}:1 on every surface (worst #{$worst}:1)';
+}

package/src/styles/variables/index.scss

@@ -1,5 +1,6 @@
 @forward 'layout';
 @forward 'colors';
+@forward 'categories';
 @forward 'type';
 @forward 'breakpoints';
 @forward 'grid';

package/src/utils/treeMove.helper.ts

@@ -0,0 +1,223 @@
+/**
+ * Moving a node around a tree, as data.
+ *
+ * Dragging a row and a "Move to" picker ask the same questions, and neither of
+ * them is about the DOM: where may this node go, and what does the tree look
+ * like afterwards. Every product that reorders a tree writes this again, and
+ * the one rule that is easy to miss is the one that does real damage: a node
+ * dropped into its own subtree detaches that subtree from the root, and
+ * everything under it disappears.
+ *
+ * These work on any tree of `{ id, children }` and never touch the tree they
+ * are given: a plan is a new tree of shallow copies, so every field a product
+ * carries on its nodes comes through. `NbTree` enforces the same rule for
+ * pointer drags, so a product that uses both gets one answer.
+ */
+
+/** The shape these read: an id, and children when it has any. */
+export interface ITreeMoveNode {
+  id: string
+  children?: ITreeMoveNode[]
+}
+
+/** Where a node goes: next to another node, inside it, or at the top level. */
+export type TTreeMovePlacement =
+  | { kind: 'inside'; target: string }
+  | { kind: 'before'; target: string }
+  | { kind: 'after'; target: string }
+  | { kind: 'root' }
+
+export interface ITreeMovePlan<T extends ITreeMoveNode> {
+  /** The tree after the move, as shallow copies. The original is untouched. */
+  tree: T[]
+  /** The node's new parent, or null at the top level. */
+  parentId: string | null
+  /** Its index among its new siblings. */
+  index: number
+  /** The sibling it now follows, or null when it is first. */
+  afterId: string | null
+  /** The sibling it now precedes, or null when it is last. */
+  beforeId: string | null
+}
+
+interface ILocated<T extends ITreeMoveNode> {
+  node: T
+  siblings: T[]
+  parent: T | null
+}
+
+function childrenOf<T extends ITreeMoveNode>(node: T): T[] {
+  return (node.children ?? []) as T[]
+}
+
+function locate<T extends ITreeMoveNode>(
+  nodes: T[],
+  id: string,
+  parent: T | null = null,
+): ILocated<T> | null {
+  for (const node of nodes) {
+    if (node.id === id) return { node, siblings: nodes, parent }
+    const found = locate(childrenOf(node), id, node)
+    if (found) return found
+  }
+  return null
+}
+
+/** The ids of the nodes above `id`, outermost first. Empty for a root node. */
+export function ancestorsOf<T extends ITreeMoveNode>(
+  nodes: T[],
+  id: string,
+): string[] {
+  const walk = (list: T[], trail: string[]): string[] | null => {
+    for (const node of list) {
+      if (node.id === id) return trail
+      const found = walk(childrenOf(node), [...trail, node.id])
+      if (found) return found
+    }
+    return null
+  }
+  return walk(nodes, []) ?? []
+}
+
+/** `id` and every node under it. Empty when `id` is not in the tree. */
+export function subtreeOf<T extends ITreeMoveNode>(
+  nodes: T[],
+  id: string,
+): Set<string> {
+  const out = new Set<string>()
+  const found = locate(nodes, id)
+  const walk = (node: T) => {
+    out.add(node.id)
+    childrenOf(node).forEach(walk)
+  }
+  if (found) walk(found.node)
+  return out
+}
+
+/**
+ * Whether `target` is `source` itself or somewhere under it, which is the one
+ * place a node can never go.
+ */
+export function isInvalidTarget<T extends ITreeMoveNode>(
+  nodes: T[],
+  source: string,
+  target: string,
+): boolean {
+  return subtreeOf(nodes, source).has(target)
+}
+
+/** A node `source` may move to, in reading order, with its nesting depth. */
+export interface ITreeMoveTarget<T extends ITreeMoveNode> {
+  id: string
+  depth: number
+  node: T
+}
+
+/**
+ * Every node `source` may move to: all of them but itself and its own subtree.
+ * The list a "Move to" picker offers.
+ */
+export function moveTargets<T extends ITreeMoveNode>(
+  nodes: T[],
+  source: string,
+): ITreeMoveTarget<T>[] {
+  const out: ITreeMoveTarget<T>[] = []
+  const walk = (list: T[], depth: number) => {
+    for (const node of list) {
+      if (node.id === source) continue
+      out.push({ id: node.id, depth, node })
+      walk(childrenOf(node), depth + 1)
+    }
+  }
+  walk(nodes, 0)
+  return out
+}
+
+/**
+ * The tree after moving `source` to `placement`, or null when the move is
+ * refused (into its own subtree, or a node or target that is not there) or
+ * would change nothing.
+ *
+ * "Inside" appends as the last child, so dragging a node onto its own current
+ * parent moves it to the end rather than leaving it where it was. The returned
+ * `parentId`, `index`, `afterId` and `beforeId` describe the new position, for
+ * a product to turn into whatever its own storage records.
+ */
+export function planTreeMove<T extends ITreeMoveNode>(
+  nodes: T[],
+  source: string,
+  placement: TTreeMovePlacement,
+): ITreeMovePlan<T> | null {
+  const from = locate(nodes, source)
+  if (!from) return null
+  if (placement.kind !== 'root') {
+    if (isInvalidTarget(nodes, source, placement.target)) return null
+    if (!locate(nodes, placement.target)) return null
+  }
+
+  const clone = (list: T[]): T[] =>
+    list.map((node) =>
+      node.children === undefined
+        ? ({ ...node } as T)
+        : ({ ...node, children: clone(childrenOf(node)) } as T),
+    )
+
+  const tree = clone(nodes)
+  const moving = locate(tree, source)!
+  moving.siblings.splice(moving.siblings.indexOf(moving.node), 1)
+
+  if (placement.kind === 'root' || placement.kind === 'inside') {
+    const parent =
+      placement.kind === 'root' ? null : locate(tree, placement.target)!.node
+    if (parent && parent.children === undefined) parent.children = []
+    const list = parent ? childrenOf(parent) : tree
+    list.push(moving.node)
+  } else {
+    const anchor = locate(tree, placement.target)!
+    const index = anchor.siblings.indexOf(anchor.node)
+    anchor.siblings.splice(
+      placement.kind === 'before' ? index : index + 1,
+      0,
+      moving.node,
+    )
+  }
+
+  const after = locate(tree, source)!
+  const index = after.siblings.indexOf(after.node)
+  const unchanged =
+    (after.parent?.id ?? null) === (from.parent?.id ?? null) &&
+    index === from.siblings.indexOf(from.node)
+  if (unchanged) return null
+
+  return {
+    tree,
+    parentId: after.parent?.id ?? null,
+    index,
+    afterId: index > 0 ? after.siblings[index - 1].id : null,
+    beforeId:
+      index < after.siblings.length - 1 ? after.siblings[index + 1].id : null,
+  }
+}
+
+/**
+ * A flat list in reading order, each row carrying its nesting depth, rebuilt
+ * into a tree. The shape most APIs return a tree in.
+ */
+export function nestByDepth<T extends { id: string; depth: number }>(
+  rows: T[],
+): (Omit<T, 'depth'> & { children: unknown[] })[] {
+  type TNested = Omit<T, 'depth'> & { children: TNested[] }
+  const roots: TNested[] = []
+  const stack: { node: TNested; depth: number }[] = []
+  for (const row of rows) {
+    const { depth, ...rest } = row
+    const node = { ...rest, children: [] } as unknown as TNested
+    while (stack.length > 0 && stack[stack.length - 1].depth >= depth) {
+      stack.pop()
+    }
+    if (stack.length === 0) roots.push(node)
+    else stack[stack.length - 1].node.children.push(node)
+    stack.push({ node, depth })
+  }
+  return roots
+}

package/dist/Avatar-C6pCz1lv.cjs

@@ -1 +0,0 @@
-require(`./chunk-D-qHiVGv.cjs`);const e=require(`./utils/initials.helper.cjs`);let t=require(`vue`);var n=[`role`,`aria-label`,`aria-hidden`,`title`],r=[`src`],i={key:1,class:`nb-avatar__initials`,"aria-hidden":`true`},a=(0,t.defineComponent)({__name:`Avatar`,props:{name:{default:void 0},email:{default:void 0},picture:{default:void 0},size:{default:`md`},decorative:{type:Boolean,default:!1}},setup(a){let o=a,s=(0,t.ref)(!1);(0,t.watch)(()=>o.picture,()=>{s.value=!1});let c=(0,t.computed)(()=>!!o.picture&&!s.value),l=(0,t.computed)(()=>e.initialsOf(o)),u=(0,t.computed)(()=>o.name?.trim()||o.email?.trim()||``);return(e,o)=>((0,t.openBlock)(),(0,t.createElementBlock)(`span`,{class:(0,t.normalizeClass)([`nb-avatar`,[`nb-avatar--${a.size}`]]),role:a.decorative?void 0:`img`,"aria-label":a.decorative?void 0:u.value||void 0,"aria-hidden":a.decorative?`true`:void 0,title:a.decorative?void 0:u.value||void 0},[c.value?((0,t.openBlock)(),(0,t.createElementBlock)(`img`,{key:0,class:`nb-avatar__picture`,src:a.picture??void 0,alt:``,onError:o[0]||=e=>s.value=!0},null,40,r)):((0,t.openBlock)(),(0,t.createElementBlock)(`span`,i,(0,t.toDisplayString)(l.value),1))],10,n))}});Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return a}});

package/dist/Avatar-DdI07lRT.js

@@ -1,47 +0,0 @@
-import { initialsOf as e } from "./utils/initials.helper.mjs";
-import { computed as t, createElementBlock as n, defineComponent as r, normalizeClass as i, openBlock as a, ref as o, toDisplayString as s, watch as c } from "vue";
-//#region src/components/Avatar.vue?vue&type=script&setup=true&lang.ts
-var l = [
-	"role",
-	"aria-label",
-	"aria-hidden",
-	"title"
-], u = ["src"], d = {
-	key: 1,
-	class: "nb-avatar__initials",
-	"aria-hidden": "true"
-}, f = /* @__PURE__ */ r({
-	__name: "Avatar",
-	props: {
-		name: { default: void 0 },
-		email: { default: void 0 },
-		picture: { default: void 0 },
-		size: { default: "md" },
-		decorative: {
-			type: Boolean,
-			default: !1
-		}
-	},
-	setup(r) {
-		let f = r, p = o(!1);
-		c(() => f.picture, () => {
-			p.value = !1;
-		});
-		let m = t(() => !!f.picture && !p.value), h = t(() => e(f)), g = t(() => f.name?.trim() || f.email?.trim() || "");
-		return (e, t) => (a(), n("span", {
-			class: i(["nb-avatar", [`nb-avatar--${r.size}`]]),
-			role: r.decorative ? void 0 : "img",
-			"aria-label": r.decorative ? void 0 : g.value || void 0,
-			"aria-hidden": r.decorative ? "true" : void 0,
-			title: r.decorative ? void 0 : g.value || void 0
-		}, [m.value ? (a(), n("img", {
-			key: 0,
-			class: "nb-avatar__picture",
-			src: r.picture ?? void 0,
-			alt: "",
-			onError: t[0] ||= (e) => p.value = !0
-		}, null, 40, u)) : (a(), n("span", d, s(h.value), 1))], 10, l));
-	}
-});
-//#endregion
-export { f as t };

package/dist/TreeContext-BH2qpPud.cjs

@@ -1 +0,0 @@
-var e=Symbol(`nb-tree`),t=Symbol(`nb-tree-depth`);Object.defineProperty(exports,`n`,{enumerable:!0,get:function(){return e}}),Object.defineProperty(exports,`t`,{enumerable:!0,get:function(){return t}});

package/dist/TreeContext-DMADOfuO.js

@@ -1,4 +0,0 @@
-//#region src/components/TreeContext.ts
-var e = Symbol("nb-tree"), t = Symbol("nb-tree-depth");
-//#endregion
-export { e as n, t };