@crewlethq/ui 0.4.3 → 0.5.0

package/dist/SidebarNav/SidebarNav.d.ts

@@ -1,19 +1,29 @@
 /**
  * The rail's navigation: groups of rows, one of which says where the reader is.
  *
- * THE ROW THE READER IS ON IS THE ONE PLACE THE ACCENT APPEARS IN THE CHROME,
- * and it takes the accent twice over: the accent's soft tint as its ground,
- * and the accent ink for its label and its glyph. Position AND hue, so the row
- * is found at a glance by a reader who sees the hue and by one who does not.
+ * THE ROW THE READER IS ON IS RAISED, WITH A HAIRLINE ROUND IT, AND NO HUE: it
+ * is found by its position, its lift and its line, by a reader who sees
+ * colour and by one who does not. The accent is the primary action's fill, so
+ * a violet row in the rail would read as a second primary on every screen.
  * `aria-current="page"` says the same thing to a screen reader, and the style
  * is drawn FROM that attribute, so the two cannot come apart. The stylesheet
- * carries why this replaced a one-pixel accent bar outside the row's edge.
+ * carries why the hairline is an outline rather than a shadow.
  *
  * THE LINK ELEMENT BELONGS TO THE APPLICATION (`renderLink`). A router's own
  * link is what carries a client navigation and a leave guard; a plain anchor is
  * what carries a middle click into a new tab. Neither is right everywhere, so
  * neither is built in: the engine keeps plain anchors and the console passes
  * its router's NavLink.
+ *
+ * A FIGURE AT THE END OF A ROW IS ONE OF TWO THINGS, and the two are two props
+ * rather than one prop with a tone. A `count` is how many of something the
+ * destination holds (the open tasks in a project), a quiet figure in the
+ * tertiary ink; a `badge` is how many things are waiting on the reader (the
+ * unread in the inbox), the one filled pill in the chrome. Both are READ as
+ * part of the row's name, with the words the caller gives them ("Inbox, 5
+ * unread"), because a bare "5" after a name says nothing about what it counts,
+ * and both carry those words as required props, so a figure without them does
+ * not type-check.
  */
 import { type MouseEventHandler, type ReactNode } from 'react';
 export interface SidebarNavProps {
@@ -26,6 +36,24 @@ export interface SidebarNavProps {
     className?: string | undefined;
     children?: ReactNode;
 }
+/**
+ * The one control a group's heading can carry at its end: the add beside
+ * "Projects".
+ *
+ * A DESCRIPTION RATHER THAN AN ELEMENT, because the rail is what draws it: a
+ * square at the pointer-target floor, which is exactly the heading's height,
+ * named by `label`, with its ring inside its own box like every row in a
+ * clipping scroller. A control handed in whole would bring its own step, and
+ * the smallest one in the kit is two pixels taller than the heading it sits
+ * in.
+ */
+export interface NavGroupAction {
+    /** What pressing it does, in words: "New project". It is the control's name. */
+    label: string;
+    /** The glyph. Decoration: the label is the name. */
+    icon: ReactNode;
+    onClick: MouseEventHandler<HTMLButtonElement>;
+}
 export interface NavGroupProps {
     /**
      * The group's heading. Without one the rows are simply a run of rows, and an
@@ -34,6 +62,13 @@ export interface NavGroupProps {
      * rail spent on nothing.
      */
     label?: ReactNode;
+    /**
+     * A control at the end of the heading. It is a sibling of the heading's
+     * words rather than part of them, so the group is still named by its label
+     * alone, and it takes its own place in the tab order before the group's
+     * first row.
+     */
+    action?: NavGroupAction | undefined;
     className?: string | undefined;
     children?: ReactNode;
 }
@@ -46,33 +81,58 @@ export interface NavLinkProps {
     onClick?: MouseEventHandler<HTMLElement> | undefined;
 }
 /**
- * How loudly a row's badge is drawn.
+ * A figure at the end of a row, and what it counts.
  *
- * `neutral` is a quiet figure at the end of the row, in the row's own ink.
- * `attention` is the one badge in the chrome allowed a status hue: a count of
- * what is waiting on a person is the one thing that should pull the eye out of
- * whatever screen the reader is on. It is a tint behind a word rather than a
- * word in a hue, so it still reads to somebody who cannot separate the hue.
- *
- * A TONE RATHER THAN A COMPONENT THE CALLER PASSES IN, because the tint has to
- * clear its floor on the ground the ROW has, which is the accent tint on the
- * reader's own row. That is a fact about the rail, measured in the rail's own
- * stylesheet, and not something a call site can be asked to know.
+ * VALUES RATHER THAN AN ELEMENT, because the rail is what paints them: the
+ * pair has to clear its floor on every ground a ROW can have, the reader's
+ * own raised row included, and that is a fact about the rail, measured in the
+ * rail's own stylesheet, not something a call site can be asked to know.
  */
-export type NavBadgeTone = 'neutral' | 'attention';
+export interface NavFigure {
+    /** The figure, drawn as given, so the caller decides its formatting. */
+    value: number | string;
+    /**
+     * What is counted, read after the figure as part of the row's name:
+     * `unread` makes the inbox row "Inbox, 5 unread". Required, because a
+     * figure read with no word after it is a number nobody can place.
+     */
+    label: string;
+}
+/** A quiet figure: how many of something the destination holds. */
+export interface NavCount extends NavFigure {
+    /**
+     * A mark before the figure: the working dot beside a count of agents at
+     * work. Decoration, because the label says the same thing in words.
+     */
+    mark?: ReactNode;
+}
 export interface NavItemProps {
     /** What the row is called. */
     label: ReactNode;
     /** The row's glyph. Decoration: the label beside it carries the meaning. */
     icon?: ReactNode;
     /**
-     * A count or a state at the end of the row. The slot draws it: whatever is
-     * passed contributes its text and the name a screen reader reads after the
-     * row's own, so a `<Count>` here is a figure rather than a second pill.
+     * A short key drawn as a chip before the label, in place of a glyph: a
+     * project's `ENG`. It is text, and READ as the start of the row's name
+     * ("ENG Core platform"), because it is the prefix every item in that project
+     * is filed under and a reader who hears it can find them. A string rather
+     * than an element, because the rail paints the chip and measures it.
+     */
+    lead?: string | undefined;
+    /**
+     * How many of something the destination holds, as a quiet figure at the end
+     * of the row in the tertiary ink: the open tasks in a project.
+     */
+    count?: NavCount | undefined;
+    /**
+     * How many things at this destination are waiting on the reader, as the one
+     * filled pill in the chrome, in the accent: the unread in the inbox. A count
+     * of what is waiting on the reader is the one thing in the rail that asks
+     * them to act, which is what the accent means; it is a FILL carrying a
+     * figure rather than a figure in a hue, so it still reads to somebody who
+     * cannot separate the hue. Anything else is a `count`.
      */
-    badge?: ReactNode;
-    /** How loudly. Neutral unless this row is what needs a person. */
-    badgeTone?: NavBadgeTone | undefined;
+    badge?: NavFigure | undefined;
     href?: string | undefined;
     /** Whether this row is the screen the reader is on. */
     current?: boolean | undefined;
@@ -112,6 +172,6 @@ export declare namespace SidebarNav {
  * `<div>` here still carries the label's own padding, which put sixteen blank
  * pixels at the top of the rail and named a group nothing could read.
  */
-export declare function NavGroup({ label, className, children }: NavGroupProps): import("react").JSX.Element;
+export declare function NavGroup({ label, action, className, children }: NavGroupProps): import("react").JSX.Element;
 /** One row: a glyph, a label, an optional badge, and optionally rows beneath. */
-export declare function NavItem({ label, icon, badge, badgeTone, href, current, disabledReason, renderLink, onClick, children, expanded, defaultExpanded, onExpandedChange, expandLabel, className, }: NavItemProps): import("react").JSX.Element;
+export declare function NavItem({ label, icon, lead, count, badge, href, current, disabledReason, renderLink, onClick, children, expanded, defaultExpanded, onExpandedChange, expandLabel, className, }: NavItemProps): import("react").JSX.Element;

package/dist/SidebarNav/index.d.ts

@@ -1,3 +1,3 @@
 import './SidebarNav.css';
 export { NavGroup, NavItem, SidebarNav } from './SidebarNav.js';
-export type { NavBadgeTone, NavGroupProps, NavItemProps, NavLinkProps, SidebarNavProps } from './SidebarNav.js';
+export type { NavCount, NavFigure, NavGroupAction, NavGroupProps, NavItemProps, NavLinkProps, SidebarNavProps, } from './SidebarNav.js';

package/dist/SidebarNav/index.js

@@ -1,3 +1,3 @@
-export { NavGroup, NavItem, SidebarNav } from '../chunk-3EYF6HKB.js';
+export { NavGroup, NavItem, SidebarNav } from '../chunk-IVFJD7WY.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/SidebarNav-X5NLZNWA.css

@@ -0,0 +1,424 @@
+/*
+ * The rail's navigation.
+ *
+ * ONE VERTICAL LINE. The rail pads by --size-nav-gutter and each row pads by
+ * --size-nav-row-pad, so the mark, the group labels and every row's text start
+ * on the same line: shrink the gutter and grow the pad by the same step and
+ * nothing moves. That is why the row's own background takes the full width the
+ * gutter leaves it, rather than each row carrying a horizontal margin of its
+ * own.
+ */
+
+.crewlet-sidebar-nav {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-1);
+  min-width: 0;
+  padding: var(--spacing-2) var(--size-nav-gutter) var(--spacing-4);
+}
+
+/*
+ * THE ROWS INSIDE A GROUP ARE HALF A STEP APART: the approved design's 2px,
+ * which is what keeps a hovered row's tint from touching the raised row under
+ * it and reading as one band two rows tall. It is half a step rather than one
+ * because a rail holds fifteen destinations and more: at 4px a row the rail
+ * stood 823px in a 755px scroller when its rows were 36px, and the last two
+ * destinations were reachable only by scrolling it. At the 30px row step the
+ * same fifteen rows and fourteen 2px gaps are 478px against 540px flush at the
+ * old step, so the gap is paid for many times over by the row it sits beside.
+ */
+.crewlet-nav-group {
+  display: flex;
+  flex-direction: column;
+  gap: calc(var(--spacing-1) / 2);
+  min-width: 0;
+}
+
+/*
+ * THE HEADING: the group's name and, at its end, an optional control (the add
+ * beside "Projects"). It stands at the pointer-target floor, because that
+ * control is a target and the heading is the row it is drawn in; with no
+ * control the heading keeps the same height, so a rail whose groups differ
+ * only in whether they can add something does not change its rhythm.
+ *
+ * Held off the run above by a margin rather than a padding, so its height
+ * does not depend on the document's box-sizing: with the rail's own gap it is
+ * 14px, the design's space between two runs, at density 1.
+ *
+ * Its end inset is a step SHORTER than a row's, because the control is a
+ * 24px square with its glyph centred in it: the row pad would put the glyph
+ * five pixels inside the line every count above and below it ends on.
+ */
+.crewlet-nav-group__head {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2);
+  min-width: 0;
+  min-height: var(--size-target-min);
+  margin-top: calc(var(--spacing-2) + var(--spacing-1) / 2);
+  padding: 0 var(--spacing-2) 0 var(--size-nav-row-pad);
+}
+
+/*
+ * The group's name in the design's register: sentence case at the caption
+ * step, not the uppercase micro-label it was. It is the same case as every row
+ * it names, so "Projects" reads as the word it is rather than as a label
+ * shouted over the rows, and the quieter ink rather than the tracking is what
+ * sets it apart from them.
+ */
+.crewlet-nav-group__label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-family: var(--font-family-sans);
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-regular);
+  line-height: var(--font-line-height-tight);
+  /* The 4.5:1 step: a group name is a fact a reader has to read, not
+     decoration. */
+  color: var(--color-text-tertiary);
+}
+
+/* The heading's control. Pushed to the end whether or not the heading has
+   words, and at the floor the heading stands at. */
+.crewlet-nav-group__action {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--size-target-min);
+  height: var(--size-target-min);
+  margin-left: auto;
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--color-text-tertiary);
+  cursor: pointer;
+  transition:
+    background var(--motion-duration-fast) var(--motion-easing-default),
+    color var(--motion-duration-fast) var(--motion-easing-default);
+}
+
+.crewlet-nav-group__action:hover {
+  background: var(--color-surface-hover);
+  color: var(--color-text-primary);
+}
+
+/* Inside its own box, like every control in the rail: the rail is a clipping
+   scroller. */
+.crewlet-nav-group__action:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: var(--size-focus-ring-inset-offset);
+}
+
+.crewlet-nav-group__action-icon {
+  display: inline-flex;
+}
+
+.crewlet-nav-item {
+  min-width: 0;
+}
+
+.crewlet-nav-item__head {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-1);
+  min-width: 0;
+}
+
+.crewlet-nav-item__row {
+  display: flex;
+  align-items: center;
+  /* The design's 10px between a glyph and its word. */
+  gap: calc(var(--spacing-2) + var(--spacing-1) / 2);
+  flex: 1 1 auto;
+  min-width: 0;
+  width: 100%;
+  /* The rail's own row step, 30px: a list's 36px row spent six pixels fifteen
+     times over in a column the height of the window. */
+  min-height: var(--size-nav-row);
+  padding: 0 var(--size-nav-row-pad);
+  border: none;
+  /* The chrome's radius, not a card's. A 12px corner on a 30px row leaves the
+     tint reading as a lozenge floating in the gutter rather than as a band the
+     width of the rail. */
+  border-radius: var(--radius-md);
+  background: transparent;
+  /*
+   * A RESTING ROW IS THE SECONDARY STEP, and the reader's own row and a
+   * pointed one lift to the primary. That step is what says which row is
+   * which before the fill does: at full ink every row carried the current
+   * row's own weight, so the rail read heavier and brighter than the approved
+   * design and the current row was found by its lift alone. The secondary step
+   * is held at 4.5:1 on the rail and under the hover overlay by
+   * @crewlethq/tokens (RAIL_PAINTS), so quieter is not fainter.
+   *
+   * The glyph has no colour of its own: it is drawn in currentColor and so is
+   * this ink, on every row, which is what keeps a row from painting its word
+   * and its glyph two different answers to "where am I".
+   */
+  color: var(--color-text-secondary);
+  font-family: var(--font-family-sans);
+  /* THE CHROME IS NOT BODY TEXT. A rail row names a destination; it is read at
+     a glance and never read through, so it takes the compact step in the
+     medium weight, which is what keeps a one-word row legible at 13px. */
+  font-size: var(--font-size-compact);
+  font-weight: var(--font-weight-medium);
+  letter-spacing: var(--font-letter-spacing-snug);
+  line-height: var(--font-line-height-tight);
+  text-align: left;
+  text-decoration: none;
+  cursor: pointer;
+  transition:
+    background var(--motion-duration-fast) var(--motion-easing-default),
+    color var(--motion-duration-fast) var(--motion-easing-default);
+}
+
+.crewlet-nav-item__row:hover {
+  background: var(--color-surface-hover);
+  color: var(--color-text-primary);
+  text-decoration: none;
+}
+
+/*
+ * WHERE THE READER IS: the row stands on RAISED, with the plain border drawn
+ * round it as a hairline INSIDE the row, and lifts to the primary ink.
+ *
+ * It is found the way a card is found. In light, raised is only dE 1.84 off
+ * the frame the rail stands on, so the fill alone is a lift a reader may not
+ * see; the hairline is what carries the row, and in dark it is also what
+ * tells the current row from a hovered one, whose fill lands only dE 1.56
+ * away. @crewlethq/tokens holds both halves by name: the row lifts off the
+ * rail by dE 1.5 and the hairline clears dE 3 on the row it is drawn on.
+ *
+ * It used to be the accent's own soft tint with the label in the accent ink.
+ * The accent is the fill of the primary action now, so a violet row in the
+ * rail would read as a second primary on every screen, beside the one the
+ * screen is actually asking for. Where the reader is, is the row's position,
+ * its lift and its line; aria-current says it to a screen reader.
+ *
+ * THE HAIRLINE IS AN OUTLINE, not an inset box-shadow, for the reason the
+ * focus ring is one: forced-colors mode drops every box-shadow and every
+ * background and keeps outlines, so drawn as a shadow the current row would
+ * be indistinguishable from its neighbours for exactly the readers that mode
+ * exists for. The focus ring is the same property, so its rule is declared
+ * after this one and a focused current row draws the ring instead.
+ *
+ * Drawn from aria-current, so the picture and what a screen reader is told
+ * cannot come apart. It is declared after :hover deliberately: both selectors
+ * weigh the same, a row shows the current lift or the hover overlay and never
+ * both, and later is what decides which.
+ */
+.crewlet-nav-item__row[aria-current='page'] {
+  background: var(--color-surface-elevated);
+  outline: 1px solid var(--color-border-default);
+  outline-offset: -1px;
+  color: var(--color-text-primary);
+}
+
+.crewlet-nav-item__row[aria-disabled='true'] {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+.crewlet-nav-item__row[aria-disabled='true']:hover {
+  background: transparent;
+  color: var(--color-text-secondary);
+}
+
+/*
+ * After the current row's rule, which draws its hairline on the same
+ * property: both weigh the same, so source order is what lets a focused
+ * current row draw the ring rather than the line.
+ */
+.crewlet-nav-item__row:focus-visible {
+  outline: 2px solid var(--color-focus);
+  /* Inside the row's own box: the rail is a clipping scroller, so an outset
+     ring on the first or last row is cut off by it. */
+  outline-offset: var(--size-focus-ring-inset-offset);
+}
+
+/*
+ * THE GLYPH IS THE LABEL'S INK. Lucide draws in currentColor, so the glyph
+ * takes whatever the row is painted in, at rest, pointed and current alike,
+ * and there is no second ramp to fall out of step with the word beside it.
+ */
+.crewlet-nav-item__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+}
+
+.crewlet-nav-item__label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/*
+ * A PROJECT'S KEY, as a chip in the glyph's place: the prefix every item in
+ * the project is filed under, in mono so ENG and PROD line up by letter. It
+ * is the raised rung inside the plain hairline, in the secondary ink, which
+ * the palette suite measures on every ground a row can have; on the reader's
+ * own row, which is raised too, the hairline is what draws it.
+ */
+.crewlet-nav-item__lead {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+  padding: 0 calc(var(--spacing-1) + 1px);
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-xs);
+  background: var(--color-surface-elevated);
+  color: var(--color-text-secondary);
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-2xs);
+  font-weight: var(--font-weight-medium);
+  letter-spacing: var(--font-letter-spacing-normal);
+  line-height: var(--font-line-height-body);
+}
+
+/*
+ * THE COUNT: how many of something the destination holds, as a quiet figure
+ * at the end of the row. Tabular, so a count that ticks up does not move the
+ * words beside it. A mark before it (the working dot beside a count of agents
+ * at work) stands half a step off the figure.
+ */
+.crewlet-nav-item__count {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+  margin-left: auto;
+  font-size: var(--font-size-2xs);
+  font-variant-numeric: tabular-nums;
+  color: var(--color-text-tertiary);
+}
+
+.crewlet-nav-item__figure {
+  display: inline-flex;
+  align-items: center;
+  gap: calc(var(--spacing-1) + 1px);
+}
+
+.crewlet-nav-item__mark {
+  display: inline-flex;
+}
+
+/* The count takes the row's ink on the current row, lifting from the tertiary
+   step to the primary ink with the row it sits in: the tertiary step is
+   measured on the rail and under the hover overlay, and the raised row is a
+   ground it was never held to. */
+.crewlet-nav-item__row[aria-current='page'] .crewlet-nav-item__count {
+  color: inherit;
+}
+
+/*
+ * THE BADGE, THE ONE FIGURE IN THE CHROME ALLOWED A HUE, and it is the
+ * accent. A count of what is waiting on the reader is the one thing in the
+ * rail that asks them to act, which is what the accent means, and it is the
+ * one thing that should pull the eye out of whatever screen they are on. It
+ * is a FILL carrying a figure rather than a figure in a hue, so it reads to
+ * somebody who cannot separate the hue at all: the filled pill is the signal,
+ * the figure is the count.
+ *
+ * The design's 18px pill, at least as wide as it is tall so a single digit is
+ * a round mark and not a lozenge, and following the density like the xs Tag
+ * it matches. The label is the on-accent step, the primary action's own pair,
+ * on every row alike, because the fill is opaque.
+ */
+.crewlet-nav-item__badge {
+  --crewlet-nav-item-badge-size: calc(18px * var(--density, 1));
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  box-sizing: border-box;
+  min-width: var(--crewlet-nav-item-badge-size);
+  height: var(--crewlet-nav-item-badge-size);
+  margin-left: auto;
+  padding: 0 calc(var(--spacing-1) + 1px);
+  border-radius: var(--radius-pill);
+  background: var(--color-brand-accent);
+  color: var(--color-text-on-accent);
+  font-size: var(--font-size-2xs);
+  font-weight: var(--font-weight-semibold);
+  font-variant-numeric: tabular-nums;
+  line-height: 1;
+}
+
+/* Beside a count the badge is the second figure, not a second push to the
+   end: two auto margins would split the room between them and float the
+   count into the middle of the row. */
+.crewlet-nav-item__count + .crewlet-nav-item__badge {
+  margin-left: var(--spacing-2);
+}
+
+.crewlet-nav-item__toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--size-control-sm);
+  height: var(--size-control-sm);
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--color-text-tertiary);
+  cursor: pointer;
+}
+
+.crewlet-nav-item__toggle:hover {
+  background: var(--color-surface-hover);
+  color: var(--color-text-primary);
+}
+
+.crewlet-nav-item__toggle:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: var(--size-focus-ring-inset-offset);
+}
+
+.crewlet-nav-item__chevron {
+  display: inline-flex;
+  transition: transform var(--motion-duration-fast) var(--motion-easing-default);
+}
+
+.crewlet-nav-item__chevron--open {
+  transform: rotate(180deg);
+}
+
+/*
+ * Nested rows carry an indent guide rather than more padding, because a run of
+ * indents with no line is a hierarchy a reader has to measure by eye. On the
+ * path the reader is on the guide steps up to the strong border: the same
+ * neutral lift the current row itself takes, and not the accent, which the
+ * rail keeps for the one count that asks the reader to act.
+ */
+.crewlet-nav-item__children {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-1);
+  margin-left: var(--size-nav-row-pad);
+  padding-left: var(--spacing-2);
+  border-left: 1px solid var(--color-border-default);
+}
+
+/* No type step of its own any more: every row in the rail reads at the compact
+   step now, and the indent guide is what says a row is nested. */
+.crewlet-nav-item__children:has(.crewlet-nav-item__row[aria-current='page']) {
+  border-left-color: var(--color-border-strong);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .crewlet-nav-group__action,
+  .crewlet-nav-item__row,
+  .crewlet-nav-item__chevron {
+    transition: none;
+  }
+}