@things-factory/shell 10.1.20 → 10.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/shell",
-  "version": "10.1.20",
+  "version": "10.1.26",
   "description": "Core module for framework",
   "bin": {
     "things-factory": "bin/things-factory",
@@ -126,5 +126,5 @@
     "pg": "^8.7.3",
     "sqlite3": "^5.0.8"
   },
-  "gitHead": "6bd01660a4b28554bbe6ae4ee58f3ff844c5af69"
+  "gitHead": "151bda14d899442c6846532ddded1e2bfe23a2f5"
 }

package/tests/control-height-tokens.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Control heights: the shell theme declares the tokens, and @operato/styles declares the same names
+ * with the same defaults (ADR-0060 decision 6). The theme is the value of record; the components need
+ * a fallback because they cannot see the shell. Written in two places, so this test holds them
+ * together - change one and it fails until the other follows.
+ *
+ * Two bundles: button heights (ACTION_HEIGHT_TOKENS, ui-tokens.css) and input heights
+ * (FORM_ELEMENT_HEIGHT_TOKENS, spacing.css). Material buttons, text fields, selects and chips are
+ * sized once in the theme from those tokens.
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import path from 'path'
+
+const THEMES = path.resolve(__dirname, '../client/themes')
+
+function stylesConstants(file: string, name: string): Record<string, number> {
+  const root = path.dirname(require.resolve('@operato/styles/package.json'))
+  const built = path.join(root, 'dist/src', file)
+
+  if (!existsSync(built)) {
+    throw new Error(`the installed @operato/styles (${root}) has no ${file} - it predates ADR-0060 decision 6`)
+  }
+
+  const body = readFileSync(built, 'utf-8').match(new RegExp(`${name}\\s*=\\s*\\{([\\s\\S]*?)\\}`))
+  if (!body) throw new Error(`${name} was not found in @operato/styles ${file}`)
+
+  return Object.fromEntries([...body[1].matchAll(/'(--[a-z-]+)':\s*(\d+)/g)].map(m => [m[1], Number(m[2])]))
+}
+
+function themeDeclarations(file: string): Record<string, string> {
+  const css = readFileSync(path.join(THEMES, file), 'utf-8').replace(/\/\*[\s\S]*?\*\//g, '')
+  return Object.fromEntries([...css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)].map(m => [m[1], m[2].trim()]))
+}
+
+function expectSameValues(constants: Record<string, number>, theme: Record<string, string>) {
+  for (const [token, px] of Object.entries(constants)) {
+    expect({ token, value: theme[token] }).toEqual({ token, value: `${px}px` })
+  }
+}
+
+describe('button height tokens', () => {
+  it('the shell theme declares every @operato/styles action height with the same value', () => {
+    const constants = stylesConstants('action-heights.js', 'ACTION_HEIGHT_TOKENS')
+
+    expect(Object.keys(constants).sort()).toEqual([
+      '--cell-action-height',
+      '--context-action-height',
+      '--form-action-height',
+      '--popup-action-height'
+    ])
+    expectSameValues(constants, themeDeclarations('ui-tokens.css'))
+  })
+
+  it('Material buttons take the form height, set once in the theme', () => {
+    const theme = themeDeclarations('material-theme.css')
+
+    for (const kind of ['filled', 'outlined', 'text', 'elevated', 'filled-tonal']) {
+      expect({ kind, value: theme[`--md-${kind}-button-container-height`] }).toEqual({
+        kind,
+        value: 'var(--form-action-height)'
+      })
+    }
+  })
+
+  it('assist chips draw page actions, so they take the page action height', () => {
+    expect(themeDeclarations('layout-theme.css')['--md-assist-chip-container-height']).toBe(
+      'var(--context-action-height)'
+    )
+  })
+})
+
+describe('input height tokens', () => {
+  it('the shell theme declares small, medium and large with the @operato/styles values, and nothing else', () => {
+    const constants = stylesConstants('form-element-heights.js', 'FORM_ELEMENT_HEIGHT_TOKENS')
+    const theme = themeDeclarations('spacing.css')
+
+    expect(Object.keys(constants).sort()).toEqual([
+      '--form-element-height-large',
+      '--form-element-height-medium',
+      '--form-element-height-small'
+    ])
+    expectSameValues(constants, theme)
+    expect(
+      Object.keys(theme)
+        .filter(name => name.startsWith('--form-element-height-'))
+        .sort()
+    ).toEqual(Object.keys(constants).sort())
+  })
+
+  it('an input lines up with a button on the same row (a UX layout rule)', () => {
+    /*
+     * The tokens are separate so one use can change on its own (user decision 2026-09-17). This test
+     * is a layout rule on top of that: a field and a button that stand on one row have one height.
+     * If a change here is intended, change this rule - do not put the value back to make it pass.
+     */
+    const actions = stylesConstants('action-heights.js', 'ACTION_HEIGHT_TOKENS')
+    const inputs = stylesConstants('form-element-heights.js', 'FORM_ELEMENT_HEIGHT_TOKENS')
+    const pairs = [
+      ['--form-element-height-medium', '--form-action-height'],
+      ['--form-element-height-small', '--cell-action-height']
+    ] as const
+
+    for (const [input, button] of pairs) {
+      if (inputs[input] !== actions[button]) {
+        throw new Error(
+          `${input} (${inputs[input]}px) and ${button} (${actions[button]}px) stand on one row but differ in height. ` +
+            'If that is intended, change this layout rule; do not put the value back to make it pass.'
+        )
+      }
+    }
+  })
+
+  it('outlined Material fields take medium, filled ones take large', () => {
+    const theme = themeDeclarations('material-theme.css')
+    const space = (size: string, less: number) => `calc((var(--form-element-height-${size}) - ${less}px) / 2)`
+
+    for (const name of [
+      '--md-outlined-text-field-top-space',
+      '--md-outlined-text-field-bottom-space',
+      '--md-outlined-field-top-space',
+      '--md-outlined-field-bottom-space'
+    ]) {
+      expect({ name, value: theme[name] }).toEqual({ name, value: space('medium', 20) })
+    }
+
+    for (const name of [
+      '--md-filled-text-field-top-space',
+      '--md-filled-text-field-bottom-space',
+      '--md-filled-field-top-space',
+      '--md-filled-field-bottom-space'
+    ]) {
+      expect({ name, value: theme[name] }).toEqual({ name, value: space('large', 20) })
+    }
+
+    for (const name of ['--md-filled-text-field-with-label-top-space', '--md-filled-field-with-label-bottom-space']) {
+      expect({ name, value: theme[name] }).toEqual({ name, value: space('large', 34) })
+    }
+
+    expect(theme['--md-filter-chip-container-height']).toBe('var(--form-element-height-small)')
+  })
+})

package/tests/error-colour-contrast.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Error text has to be readable - on its own container, as a filled chip, and on the page.
+ *
+ * Until 2026-09-17 it was not: light `error` on `surface` measured 2.95 and `on-error-container`
+ * on `error-container` 2.41; dark `on-error` on `error` and `on-error-container` on
+ * `error-container` were both 1.75. WCAG 1.4.3 asks 4.5 for text. A refusal message drawn in the
+ * error colour was the hardest line on the screen to read, on exactly the screens where reading it
+ * matters.
+ *
+ * The fix kept each colour's OKLCH hue and chroma and only moved lightness, so red is still the
+ * same red - only darker where it sits on light, and a dark red under the pink in dark mode.
+ *
+ * Every app without its own light.css / dark.css receives these values, so this is a platform-wide
+ * change on purpose: a failing contrast is a defect, not a choice.
+ */
+
+import { readFileSync } from 'fs'
+import path from 'path'
+
+const THEMES = path.resolve(__dirname, '../client/themes')
+
+/** WCAG 1.4.3 minimum for normal text. */
+const TEXT = 4.5
+
+function slotsOf(file: string): Map<string, string> {
+  const css = readFileSync(path.join(THEMES, file), 'utf-8')
+  return new Map([...css.matchAll(/--md-sys-color-([a-z-]+)\s*:\s*([^;]+);/g)].map(m => [m[1], m[2].trim()]))
+}
+
+/** Accepts `#rrggbb` and `rgb(r g b)`; a `var(--x, <colour>)` resolves to its fallback. */
+function rgbOf(value: string): [number, number, number] {
+  const fallback = value.match(/^var\(--[a-z-]+, (.*)\)$/)
+  const v = fallback ? fallback[1] : value
+
+  const hex = v.match(/^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/)
+  if (hex) return [parseInt(hex[1], 16), parseInt(hex[2], 16), parseInt(hex[3], 16)]
+
+  const rgb = v.match(/^rgb\((\d+)\s+(\d+)\s+(\d+)\)$/)
+  if (rgb) return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])]
+
+  throw new Error(`cannot read colour: ${value}`)
+}
+
+function luminance([r, g, b]: [number, number, number]): number {
+  const lin = (c: number) => {
+    const s = c / 255
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+  }
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)
+}
+
+function contrast(a: string, b: string): number {
+  const [hi, lo] = [luminance(rgbOf(a)), luminance(rgbOf(b))].sort((x, y) => y - x)
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+/** [text slot, background slot] - where the error colour is read as text. */
+const PAIRS: [string, string][] = [
+  ['on-error', 'error'],
+  ['on-error-container', 'error-container'],
+  ['error', 'surface'],
+  ['error', 'surface-container-highest']
+]
+
+describe.each(['light.css', 'dark.css'])('error colours in shell %s', file => {
+  const slots = slotsOf(file)
+
+  it.each(PAIRS)('%s on %s reaches 4.5:1', (text, background) => {
+    expect(slots.has(text) && slots.has(background)).toBe(true)
+    expect(contrast(slots.get(text)!, slots.get(background)!)).toBeGreaterThanOrEqual(TEXT)
+  })
+})

package/tests/md-sys-slot-owners.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Who may set each md-sys colour slot - decided by the shell theme, not by a document.
+ *
+ * ── Why the shell opens slots instead of apps replacing files ─────────────────
+ * The theme plugin replaces a stylesheet by file name, so an app that ships its own `light.css`
+ * takes all 49 slots: neutrals, outline, error. Products then disagree on what grey and red mean, and
+ * a fix to the shared `light.css` silently never reaches them. Ordering cannot fix it either: the
+ * plugin puts app files before the shell's, so an app's `.light { --md-sys-color-primary }` loses to
+ * the shell `light.css` behind it at equal specificity (measured on a running app bundle, 2026-09-17).
+ *
+ * So the shell declares slots as `var(--<owner>-<slot>, <shell value>)`. Custom properties resolve at
+ * compute time, so bundle order stops mattering, and a slot that is not opened cannot be reached.
+ *
+ * Three owners, one mechanism - no reliance on bundle order or specificity:
+ *   --brand-<slot>   a product's accent (its own brand.css)                26 slots
+ *   --suite-<slot>   the operato suite's shared greys (@things-factory/operato-suite)  17 slots
+ *   closed           error x4, shadow, scrim - literal, nobody above the platform sets them  6 slots
+ * A tenant's domain theme still wins over all of these: it writes --md-sys-color-* directly, later in
+ * the bundle. Apps with neither brand.css nor the suite get the fallbacks, the shell values of before.
+ *
+ * If md adds a slot the counts go red on purpose: someone has to decide whose it is.
+ */
+
+import { readFileSync } from 'fs'
+import path from 'path'
+
+const THEMES = path.resolve(__dirname, '../client/themes')
+
+const ACCENTS = ['primary', 'secondary', 'tertiary']
+
+const BRAND = new Set([
+  ...ACCENTS.flatMap(a => [
+    a,
+    `on-${a}`,
+    `${a}-container`,
+    `on-${a}-container`,
+    `${a}-fixed`,
+    `on-${a}-fixed`,
+    `${a}-fixed-dim`,
+    `on-${a}-fixed-variant`
+  ]),
+  'surface-tint',
+  'inverse-primary'
+])
+
+const SUITE = new Set([
+  'background',
+  'on-background',
+  'surface',
+  'on-surface',
+  'surface-variant',
+  'on-surface-variant',
+  'outline',
+  'outline-variant',
+  'inverse-surface',
+  'inverse-on-surface',
+  'surface-dim',
+  'surface-bright',
+  'surface-container-lowest',
+  'surface-container-low',
+  'surface-container',
+  'surface-container-high',
+  'surface-container-highest'
+])
+
+function slotsOf(file: string): Map<string, string> {
+  const css = readFileSync(path.join(THEMES, file), 'utf-8')
+  return new Map([...css.matchAll(/--md-sys-color-([a-z-]+)\s*:\s*([^;]+);/g)].map(m => [m[1], m[2].trim()]))
+}
+
+const opened = (prefix: string, slot: string) =>
+  new RegExp(`^var\\(--${prefix}-${slot}, (#[0-9a-fA-F]{3,8}|rgba?\\([^()]*\\))\\)$`)
+
+describe.each(['light.css', 'dark.css'])('shell %s opens accent to products and neutrals to the suite', file => {
+  const slots = slotsOf(file)
+  const names = [...slots.keys()]
+
+  it('declares 49 slots: 26 brand, 17 suite, 6 closed', () => {
+    expect(BRAND.size).toBe(26)
+    expect(SUITE.size).toBe(17)
+    expect(slots.size).toBe(49)
+    expect(names.filter(s => BRAND.has(s)).length).toBe(26)
+    expect(names.filter(s => SUITE.has(s)).length).toBe(17)
+    expect(names.filter(s => !BRAND.has(s) && !SUITE.has(s)).length).toBe(6)
+  })
+
+  it('reads brand slots from --brand-<slot> and suite slots from --suite-<slot>, each with a colour fallback', () => {
+    for (const [slot, value] of slots) {
+      if (BRAND.has(slot)) expect({ slot, value }).toEqual({ slot, value: expect.stringMatching(opened('brand', slot)) })
+      if (SUITE.has(slot)) expect({ slot, value }).toEqual({ slot, value: expect.stringMatching(opened('suite', slot)) })
+    }
+  })
+
+  it('keeps the closed slots literal', () => {
+    for (const [slot, value] of slots) {
+      if (BRAND.has(slot) || SUITE.has(slot)) continue
+      expect({ slot, value }).toEqual({ slot, value: expect.not.stringContaining('var(') })
+    }
+  })
+})

package/tests/popup-buttons-class-shrinks.test.ts

@@ -0,0 +1,83 @@
+/**
+ * The `.buttons` row of CommonPopupStyles is on its way out; this list may only shrink.
+ *
+ * ── Why ──────────────────────────────────────────────────────────────────────
+ * Popup command rows were written as markup under a CSS convention (`<div class="buttons">`), and
+ * nine different rows grew out of that. The row is now an element, `<ox-popup-actions>` from
+ * @operato/popup, which owns order, height, shape and the destructive colour.
+ *
+ * Until every popup has moved, the old rule and the element coexist. Two things keep that from
+ * becoming permanent:
+ *
+ * - a file on this list that no longer uses `.buttons` fails - the move happened, so the list must
+ *   say so (a list that is never updated stops watching anything);
+ * - a file not on this list that starts using `.buttons` fails - new popups use the element.
+ *
+ * When the list is empty here, and in operato-application's own copy of this test, the `.buttons`
+ * rule itself is removed from @operato/styles.
+ *
+ * This test reads only this repository. Each repository keeps its own list.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'fs'
+import path from 'path'
+
+const REPO_ROOT = path.resolve(__dirname, '../../..')
+const PACKAGES = path.join(REPO_ROOT, 'packages')
+
+const SKIP = new Set(['node_modules', 'dist', 'dist-client', 'dist-server', 'dist-shared', 'coverage'])
+
+/** Files that still render the CommonPopupStyles `.buttons` row, as of 2026-09-17. */
+const STILL_USING = [
+  'auth-ui/client/components/app-binding-detail.ts',
+  'auth-ui/client/components/appliance-editor.ts',
+  'auth-ui/client/components/application-editor.ts',
+  'organization/client/component/approval-line-items-editor-popup.ts',
+  'organization/client/component/approval-line-selector.ts',
+  'organization/client/component/assignees-editor-popup.ts',
+  'organization/client/component/department-selector.ts',
+  'organization/client/component/recipients-editor-popup.ts'
+]
+
+function clientSources(dir: string, found: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP.has(entry) || entry.startsWith('.')) continue
+
+    const full = path.join(dir, entry)
+    let stat
+    try {
+      stat = statSync(full)
+    } catch {
+      continue
+    }
+
+    if (stat.isDirectory()) clientSources(full, found)
+    else if (entry.endsWith('.ts') && full.includes(`${path.sep}client${path.sep}`)) found.push(full)
+  }
+  return found
+}
+
+/** Uses the row: takes CommonPopupStyles and renders an element with the `buttons` class. */
+function usesButtonsRow(source: string): boolean {
+  return /\bCommonPopupStyles\b/.test(source) && /class\s*=\s*["'](?:[^"']*\s)?buttons(?:\s[^"']*)?["']/.test(source)
+}
+
+describe('the CommonPopupStyles .buttons row only shrinks', () => {
+  const files = clientSources(PACKAGES)
+  const using = files
+    .filter(file => usesButtonsRow(readFileSync(file, 'utf-8')))
+    .map(file => path.relative(PACKAGES, file).split(path.sep).join('/'))
+    .sort()
+
+  it('scanned enough client sources for the answer to mean something', () => {
+    expect(files.length).toBeGreaterThanOrEqual(800)
+  })
+
+  it('has no file on the list that already moved to ox-popup-actions', () => {
+    expect(STILL_USING.filter(file => !using.includes(file))).toEqual([])
+  })
+
+  it('has no new file using the row', () => {
+    expect(using.filter(file => !STILL_USING.includes(file))).toEqual([])
+  })
+})