@estiva-app/ui 0.21.0 → 0.22.0

package/src/Avatar.tsx

@@ -29,6 +29,9 @@ import { cn } from './cn'
  */
 const HUES = ['#56c8ff', '#ff8f6b', '#4ade8c', '#b18cff', '#ffc94d', '#ff7eb0', '#7ea8ff', '#5fdfd6']
 
+/** The colour a person's initials sit on, chosen from a key: the same key
+ *  always gives the same hue, so a face reads as theirs in every app. The
+ *  eight are a fallback palette, not tokens — see the note above `HUES`. */
 export const hueFor = (key: string) => {
   let h = 0
   for (let i = 0; i < key.length; i++) h = (h * 31 + key.charCodeAt(i)) | 0

package/src/ChipInput.tsx

@@ -54,6 +54,9 @@ export interface InputChipProps {
   className?: string
 }
 
+/** A chip standing on its own: a label, an optional leading icon, an optional
+ *  ✕. For a caller that keeps its own list. Inside a `ChipInput` the same look
+ *  goes onto Base UI's `Combobox.Chip`, which joins the field's keyboard. */
 export function InputChip({ label, leading, onRemove, removeLabel, truncate, className }: InputChipProps) {
   return (
     <div className={cn(CHIP_BOX, chipPadding(!!leading, !!onRemove), className)}>

package/src/CommandPalette.tsx

@@ -237,6 +237,9 @@ export interface CommandPaletteSearchProps {
 
 type ListGroup = { value: string; items: CommandPaletteRow[] }
 
+/** The palette as a search: a query field, rows in labelled groups walked with
+ *  the arrow keys, and what to show while nothing has arrived and when nothing
+ *  matches. */
 export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups, chip, pending, notes = [], empty, children }: CommandPaletteSearchProps) {
   const { modKey, popupRef } = usePalette('CommandPaletteSearch')
   const back = useBack(chip, popupRef)
@@ -478,6 +481,9 @@ function isTextField(el: Element | null): el is HTMLInputElement | HTMLTextAreaE
   return el instanceof HTMLInputElement && TEXT_TYPES.has(el.getAttribute('type') ?? '') && el.getAttribute('role') !== 'combobox' && el.tabIndex >= 0
 }
 
+/** The palette as a form: fields, one submit button, and Ctrl+Enter — both ways
+ *  in run Base UI's field check. It shows what it is working on and what failed,
+ *  and sends focus to the first field that needs something. */
 export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWaits, working, error, children }: CommandPaletteFormProps) {
   const { modKey, popupRef } = usePalette('CommandPaletteForm')
   const back = useBack(chip, popupRef)

package/src/IdentityMenu.tsx

@@ -62,6 +62,9 @@ export interface IdentityPanelProps extends Omit<IdentityMenuProps, 'compact'> {
   onClose?: () => void
 }
 
+/** The identity rows on a panel of their own, with no menu around them — for a
+ *  docs page, or anywhere the panel is already placed. `IdentityMenu` is the
+ *  same rows inside a real menu. */
 export function IdentityPanel({ className, onClose = () => {}, ...rest }: IdentityPanelProps) {
   return (
     <MenuPanel className={cn('w-72', className)}>

package/src/Menu.tsx

@@ -86,6 +86,10 @@ export interface MenuPanelProps extends Omit<ComponentPropsWithRef<'div'>, 'chil
   children?: ReactNode
 }
 
+/** The menu's surface without the menu: the elevated box, the rows' padding,
+ *  and a divider that runs the full width of what it separates. `Menu` renders
+ *  its popup as one. On its own it is for the places that draw a menu's look
+ *  but not its behaviour — a docs page, Peek's `@`, `/` and `[` pickers. */
 export function MenuPanel({ children, className, ...props }: MenuPanelProps) {
   return (
     <div
@@ -277,6 +281,9 @@ export interface MenuSubProps {
   className?: string
 }
 
+/** A row that opens another menu beside it; its rows are this row's children.
+ *  Never inside a menu opened on hover — leaving the submenu strands both open,
+ *  measured below. */
 export function MenuSub({ label, leading, selected, children, className }: MenuSubProps) {
   /*
    * A submenu inside a hover-opened menu strands it.

package/src/Skeleton.tsx

@@ -10,6 +10,8 @@ import { cn } from './cn'
  * A list reveals after 150ms (`animate-skeleton-in`, in the preset) so a
  * fast load never flashes a skeleton — Peek's rule.
  */
+/** One pulsing bar at the inset colour: the piece every placeholder here is
+ *  built from. It draws nothing of its own — give it a width and a height. */
 export function SkeletonBar({ className, style }: { className?: string; style?: CSSProperties }) {
   return <div className={cn('bg-bg-inset rounded-sm animate-pulse', className)} style={style} />
 }

package/src/Toast.tsx

@@ -153,6 +153,9 @@ const ToastContext = createContext<ToastValue | null>(null)
 /** D7: three on screen at once. */
 const VISIBLE_TOASTS = 3
 
+/** Mount once, near the top of an app. It owns the stack, the timers and the
+ *  portal every toast goes through, and it is what `useToast` talks to. Three
+ *  show at once; a fourth waits for one of them to close. */
 export function ToastProvider({ children }: { children: ReactNode }) {
   // One manager per provider, so `useToast` can add and close without
   // re-rendering every caller each time the list changes.
@@ -227,6 +230,8 @@ function ToastList() {
   })
 }
 
+/** How anything under a `ToastProvider` raises a toast (`showToast`) or takes
+ *  one away (`dismissToast`). Throws outside a provider. */
 export function useToast(): ToastValue {
   const ctx = useContext(ToastContext)
   if (!ctx) throw new Error('useToast must be used within ToastProvider')

package/src/Toolbar.tsx

@@ -104,6 +104,8 @@ export interface ToolbarButtonProps extends IconButtonProps {
   ref?: Ref<HTMLButtonElement>
 }
 
+/** An `IconButton` that is an item of a `Toolbar`: the arrow keys reach it, and
+ *  a disabled one stays in the walk so its reason can still be read. */
 export function ToolbarButton({ ref, disabled, disabledReason, ...props }: ToolbarButtonProps) {
   return (
     <BaseToolbar.Button
@@ -137,6 +139,8 @@ export function ToolbarButton({ ref, disabled, disabledReason, ...props }: Toolb
  */
 export type ToolbarInputProps = TextInputProps
 
+/** A `TextInput` that is an item of a `Toolbar`, so the arrow keys walk into the
+ *  field and out of it again. */
 export function ToolbarInput({ size, ...props }: ToolbarInputProps) {
   // `size` is TextInput's own (default or small), not the native attribute
   // Base UI's part would take, so it goes to the field it draws.

package/src/Tooltip.tsx

@@ -146,6 +146,10 @@ function TooltipSurface({ label, shortcut, placement }: { label: string; shortcu
   )
 }
 
+/** A tooltip on something that cannot be its own trigger — a span, a `Chip`,
+ *  an icon. It wraps what it is given in an element that carries the handlers.
+ *  A control that can be the trigger does it itself: `IconButton` takes a
+ *  `tooltip` prop, and `Button` shows a `disabledReason` the same way. */
 export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassName, children }: WithTooltipProps) {
   return (
     <BaseTooltip.Root disableHoverablePopup>

package/src/gates/app-checks.ts

@@ -216,7 +216,9 @@ export function appChecks(h: GateHelpers, { app = '.', page, chain = { ref: 'UIG
       { what: 'the gate pieces come from the package, and no repo keeps a copy', run: all(h, [
         () => h.contains(at('eslint.gates.config.js'), /from '@estiva-app\/ui\/gates'/, 'the gate config imports @estiva-app/ui/gates'),
         () => h.hook('.claude/settings.json', '@estiva-app/ui/dist/gates/cli.js'),
-        () => h.contains('package.json', /"gates:status":\s*"estiva-gates status"/, 'gates:status runs estiva-gates'),
+        // `estiva-gates status` where npm can find the command; by path where it cannot,
+        // because the install is in the app's folder and the script is in the repo's top one (Ship).
+        () => h.contains('package.json', /"gates:status":\s*"[^"]*(?:estiva-gates|@estiva-app\/ui\/dist\/gates\/cli\.js)[^"]*status/, "gates:status runs the package's engine"),
         () => (h.exists('scripts/gates-status.mjs') ? h.FAIL('scripts/gates-status.mjs is a copy of the status engine: run estiva-gates status instead') : h.PASS('no copy of the status engine')),
       ], 'the gate config, the hook and gates:status are the package\'s; no copy of the engine') },
     ]),

package/src/gates/cli.ts

@@ -4,13 +4,19 @@
  *
  *   estiva-gates count --repo <name> [--package]   write .gates-count.json (postlint:rules)
  *   estiva-gates hook [--app <dir>] [--package]    the editor gate, run by a PreToolUse hook
- *   estiva-gates status [--json] [--detail]        gates:status
+ *   estiva-gates status [--app <dir>] [--json] [--detail]   gates:status
  *
  * An app's `package.json` runs the first and the last through npm, which finds
  * the command in `node_modules/.bin`. The hook is run by path, from the
  * committed `.claude/settings.json`:
  *
  *   node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook
+ *
+ * A repo whose app sits in a folder of its own runs both by path, from the
+ * repo's top folder, and says where the app is — Ship (UIG-32):
+ *
+ *   node "$CLAUDE_PROJECT_DIR/web/node_modules/@estiva-app/ui/dist/gates/cli.js" hook --app web
+ *   node web/node_modules/@estiva-app/ui/dist/gates/cli.js status --app web
  */
 import { writeGateCount } from './count'
 import { runHook } from './hook'
@@ -43,7 +49,7 @@ async function main(): Promise<number> {
       return result.code
     }
     case 'status': {
-      process.stdout.write(`${await runStatus({ json: flag('json'), detail: flag('detail') })}${flag('json') ? '' : '\n'}`)
+      process.stdout.write(`${await runStatus({ app: value('app'), json: flag('json'), detail: flag('detail') })}${flag('json') ? '' : '\n'}`)
       return 0
     }
     default:

package/src/gates/gates.test.ts

@@ -180,4 +180,15 @@ describe('gates:status', () => {
     const json = JSON.parse(await runStatus({ root: dir, json: true }))
     expect(json.engine).toMatch(/^@estiva-app\/ui@\d+\.\d+\.\d+$/)
   })
+
+  it('finds the checks file beside the app, and still reads the repo from its top (Ship, UIG-32)', async () => {
+    // The checks file sits in `web/`, where the install is; what it names is read from the top folder.
+    const top = join(scratch, 'status-web')
+    mkdirSync(join(top, 'web', 'scripts'), { recursive: true })
+    writeFileSync(join(top, 'package.json'), JSON.stringify({ name: 'status-web', scripts: { 'gates:status': 'node web/node_modules/@estiva-app/ui/dist/gates/cli.js status --app web' } }))
+    writeFileSync(join(top, 'web', 'scripts', 'gates-checks.mjs'), "export default (h) => ({ repo: 'shipish', tickets: [\n  { ref: 'UIG-4', title: 'The chain', owner: true, checks: [{ what: 'the top folder is read', run: () => h.script('package.json', 'gates:status') }] },\n] })\n")
+    const out = await runStatus({ root: top, app: 'web' })
+    expect(out).toContain('Tickets shipish owns (1):')
+    expect(out).toContain('✅  UIG-4')
+  })
 })

package/src/gates/status.ts

@@ -5,6 +5,7 @@
  *   estiva-gates status              one row per ticket
  *   estiva-gates status --detail     every check under every row
  *   estiva-gates status --json       machine output, read by estiva-ui's run
+ *   estiva-gates status --app web    the app sits in `web/`, as Ship's does
  *
  * Every row is decided by checks on real files, a real lint run or a real
  * GitHub setting. Nothing here reads a list that someone ticks by hand.
@@ -16,8 +17,10 @@
  * copy is named as one when estiva-ui runs it; UIG-32 moves Peek and Ship off
  * theirs.
  *
- * What differs per repo is `scripts/gates-checks.mjs`, in the repo: its checks,
- * or the checks every app runs (`appChecks`) plus its own.
+ * What differs per repo is `scripts/gates-checks.mjs`, beside the app: its
+ * checks, or the checks every app runs (`appChecks`) plus its own. It sits with
+ * the app because it imports the package — `web/scripts/` in Ship, whose app,
+ * and whose install, are in `web/` (UIG-32).
  *
  * The rows and the reasons for each check are in estiva-ui docs/GATES.md §15
  * and §17.
@@ -93,7 +96,8 @@ export interface GateSpec {
   tickets: GateTicket[]
   /** estiva-ui only: every ticket, and the repos it joins in. */
   all?: TicketListEntry[]
-  siblings?: { name: string; path: string; env: string }[]
+  /** estiva-ui only: the repos beside it. `app` is the folder its app sits in: `web` in Ship. */
+  siblings?: { name: string; path: string; env: string; app?: string }[]
 }
 
 interface Row {
@@ -356,8 +360,11 @@ function statusOf(checks: CheckResult[]) {
   return fail > 0 ? 'none' : 'unknown'
 }
 
-async function runRepo(ROOT: string, h: GateHelpers): Promise<{ spec: GateSpec; report: Report }> {
-  const checksFile = join(ROOT, 'scripts', 'gates-checks.mjs')
+async function runRepo(ROOT: string, app: string, h: GateHelpers): Promise<{ spec: GateSpec; report: Report }> {
+  // The checks file sits with the app, because it imports `appChecks` from the
+  // package: in Ship that install is `web/node_modules`, not the repo's top
+  // folder (UIG-32). Everything it names is still read from the repo's top.
+  const checksFile = join(ROOT, app, 'scripts', 'gates-checks.mjs')
   const define = ((await import(pathToFileURL(checksFile).href)) as { default: (h: GateHelpers) => GateSpec }).default
   const spec = define(h)
   const git = (...a: string[]) => {
@@ -388,18 +395,22 @@ async function runRepo(ROOT: string, h: GateHelpers): Promise<{ spec: GateSpec;
 /**
  * Another repository's report. A repo on the package's engine runs it from its
  * own install; a repo still carrying `scripts/gates-status.mjs` runs that copy.
+ *
+ * `app` is the folder that repo's app sits in — `web` in Ship — where its
+ * install and its checks file are. The report is still of the whole repo.
  */
-function runSibling(dir: string, shown: string): { report?: Report; error?: string } {
+function runSibling(dir: string, app: string, shown: string): { report?: Report; error?: string } {
   const copy = join(dir, 'scripts', 'gates-status.mjs')
-  const installed = createRequire(join(dir, 'package.json'))
+  const installed = createRequire(join(dir, app, 'package.json'))
   let script = copy
   const args = ['--json']
   if (!existsSync(copy)) {
     try {
       script = join(installed.resolve('@estiva-app/ui/package.json'), '..', 'dist', 'gates', 'cli.js')
       args.unshift('status')
+      if (app !== '.') args.push('--app', app)
     } catch {
-      return { error: `${shown} has neither its own gates-status.mjs nor @estiva-app/ui installed` }
+      return { error: `${shown} has neither its own gates-status.mjs nor @estiva-app/ui installed${app === '.' ? '' : ` in ${app}`}` }
     }
     if (!existsSync(script)) return { error: `${shown} has an @estiva-app/ui with no gates engine: install 0.21.0 or later` }
   }
@@ -442,16 +453,18 @@ function summary(rows: Row[]) {
 export interface StatusOptions {
   /** The repository to report on. */
   root?: string
+  /** The folder that holds the app, relative to `root`: `web` in Ship, `.` elsewhere. */
+  app?: string
   json?: boolean
   detail?: boolean
 }
 
 /** Print where the project stands. Returns what was printed, or the JSON report. */
-export async function runStatus({ root = process.cwd(), json = false, detail = false }: StatusOptions = {}): Promise<string> {
+export async function runStatus({ root = process.cwd(), app = '.', json = false, detail = false }: StatusOptions = {}): Promise<string> {
   const ROOT = resolve(root)
   const h = helpers(ROOT)
   const shown = (dir: string) => (relative(ROOT, dir) || dir).replace(/\\/g, '/')
-  const { spec, report } = await runRepo(ROOT, h)
+  const { spec, report } = await runRepo(ROOT, app, h)
 
   if (json) return JSON.stringify(report)
 
@@ -478,7 +491,7 @@ export async function runStatus({ root = process.cwd(), json = false, detail = f
       found.push({ name: s.name, note: `not found at ${shown(dir)} (set ${s.env} to point at it)`, missing: true })
       continue
     }
-    const r = runSibling(dir, shown(dir))
+    const r = runSibling(dir, s.app ?? '.', shown(dir))
     if (!r.report) {
       found.push({ name: s.name, note: r.error ?? 'no report', missing: true })
       continue