@truenas/ui-components 0.7.5 → 0.7.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/ui-components",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/scripts/jest.config.ts

@@ -1,17 +1,21 @@
 import type { Config } from 'jest';
 
 /**
- * `yarn test:scripts` — every build script under this directory that has tests.
+ * `yarn test:scripts` — the repo's node-environment tests: every build script under this
+ * directory that has tests, plus `release-config`, which tests repo-root configuration
+ * rather than a script and lives here because this is where a node-environment Jest
+ * project already runs.
  *
- * One Jest project per script package rather than one config rooted here, because
- * `<rootDir>` inside a project config resolves to that project's own directory: each
- * package keeps pointing ts-jest at its own `tsconfig.json`, and adding the next one
- * costs a line here rather than a merge of compiler options.
+ * One Jest project per package rather than one config rooted here, because `<rootDir>`
+ * inside a project config resolves to that project's own directory: each package keeps
+ * pointing ts-jest at its own `tsconfig.json`, and adding the next one costs a line here
+ * rather than a merge of compiler options.
  */
 const config: Config = {
   projects: [
     '<rootDir>/harness-docs/jest.config.ts',
     '<rootDir>/icon-sprite/jest.config.ts',
+    '<rootDir>/release-config/jest.config.ts',
   ],
 };
 

package/scripts/release-config/commit-header-pattern.spec.ts

@@ -0,0 +1,189 @@
+/**
+ * The PR title check and the release step both decide what a commit header means, from
+ * two patterns written in two files, and nothing made them agree. A scope naming two
+ * components with a comma — `feat(autocomplete,chip-input): …` — passed the title check,
+ * merged, and then matched no header pattern at all, so the commit analyzer read it as
+ * having no type: it triggered no release and appeared in no changelog (#315).
+ *
+ * These tests read both files rather than restating either pattern, so drift in either
+ * one fails here instead of silently dropping a merged commit from the next release.
+ *
+ * They live under the library's script tests because `yarn test:scripts` is where this
+ * repo runs Jest in a node environment; what they cover is repo-root release
+ * configuration, which is why they reach four directories up.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const repoRoot = join(__dirname, '..', '..', '..', '..');
+
+interface ParserOpts {
+  headerPattern: string;
+  headerCorrespondence: string[];
+  breakingHeaderPattern: string;
+}
+
+type PluginEntry = string | [string, { parserOpts?: ParserOpts }];
+
+const releaseConfig = JSON.parse(
+  readFileSync(join(repoRoot, '.releaserc.json'), 'utf8')
+) as { plugins: PluginEntry[] };
+
+/** Every semantic-release plugin that parses commit headers, with its plugin name. */
+const parsingPlugins: [string, ParserOpts][] = [];
+
+for (const plugin of releaseConfig.plugins) {
+  if (Array.isArray(plugin)) {
+    const [name, options] = plugin;
+
+    if (options.parserOpts) {
+      parsingPlugins.push([name, options.parserOpts]);
+    }
+  }
+}
+
+/**
+ * The Bash pattern the PR title check runs, lifted from the workflow that runs it.
+ *
+ * `[[ =~ ]]` and `RegExp` both leave the end unanchored and the pattern anchors its own
+ * start, so a JS `RegExp` accepts what the check accepts for the constructs it uses:
+ * groups, alternation, character classes and `?`.
+ */
+function readPrTitlePattern(): RegExp {
+  const workflow = readFileSync(join(repoRoot, '.github/workflows/pr-title.yml'), 'utf8');
+  const assignment = /^\s*pattern='([^']+)'\s*$/m.exec(workflow);
+
+  if (!assignment) {
+    throw new Error('no `pattern=<...>` assignment found in .github/workflows/pr-title.yml');
+  }
+
+  return new RegExp(assignment[1]);
+}
+
+const prTitleCheck = readPrTitlePattern();
+
+/** What the release step reads out of a header, or null when it matches nothing. */
+function parseHeader(opts: ParserOpts, header: string): Record<string, string | undefined> | null {
+  const match = new RegExp(opts.headerPattern).exec(header);
+
+  if (!match) {
+    return null;
+  }
+
+  return Object.fromEntries(
+    opts.headerCorrespondence.map((field, index) => [field, match[index + 1]])
+  );
+}
+
+const commaScopeHeader =
+  'NAS-142381 / 27.0.0-BETA.1 / feat(autocomplete,chip-input): drive options from an async [dataSource] (#312)';
+
+/**
+ * Headers the PR title check accepts. Every one is asserted to pass the check as well as
+ * to parse, so a case that stops being realistic fails rather than passing vacuously.
+ */
+const acceptedHeaders: { name: string; header: string; type: string; scope?: string }[] = [
+  {
+    name: 'a single-word scope',
+    header: 'feat(table): let a selection survive a dataSource change',
+    type: 'feat',
+    scope: 'table',
+  },
+  {
+    name: 'the ticket and version prefix a squash commit carries',
+    header: 'NAS-143108 / 27.0.0-BETA.1 / fix(table): stop the pager aliasing pagination',
+    type: 'fix',
+    scope: 'table',
+  },
+  {
+    name: 'no scope at all',
+    header: 'chore: bump the toolchain',
+    type: 'chore',
+    scope: undefined,
+  },
+  {
+    name: 'two components separated by a comma (#315)',
+    header: commaScopeHeader,
+    type: 'feat',
+    scope: 'autocomplete,chip-input',
+  },
+  {
+    name: 'a comma and a space between components',
+    header: 'feat(autocomplete, chip-input): drive options from an async [dataSource]',
+    type: 'feat',
+    scope: 'autocomplete, chip-input',
+  },
+  {
+    name: 'a scope with a slash',
+    header: 'refactor(a11y/labels): fold the fallback into one helper',
+    type: 'refactor',
+    scope: 'a11y/labels',
+  },
+];
+
+describe('.releaserc.json', () => {
+  it('has more than one plugin parsing commit headers, one of them the commit analyzer', () => {
+    expect(parsingPlugins.length).toBeGreaterThan(1);
+    expect(parsingPlugins.map(([name]) => name)).toContain('@semantic-release/commit-analyzer');
+  });
+
+  it('gives all of them the same parser options, so notes and version bumps agree', () => {
+    const [[, first]] = parsingPlugins;
+
+    // The plugin name rides along in the assertion so a failure says which one drifted.
+    for (const [name, opts] of parsingPlugins) {
+      expect([name, opts]).toEqual([name, first]);
+    }
+  });
+});
+
+describe.each(parsingPlugins)('%s', (_pluginName, opts) => {
+  it.each(acceptedHeaders)('parses $name', ({ header, type, scope }) => {
+    expect(parseHeader(opts, header)).toMatchObject({ type, scope, subject: expect.any(String) });
+  });
+
+  it('reads a comma scope as one scope, leaving the subject whole', () => {
+    expect(parseHeader(opts, commaScopeHeader)?.subject).toBe(
+      'drive options from an async [dataSource] (#312)'
+    );
+  });
+
+  it('recognises a breaking change whose scope contains a comma', () => {
+    const breaking = new RegExp(opts.breakingHeaderPattern).exec(
+      'feat(autocomplete,chip-input)!: options are now a dataSource'
+    );
+
+    expect(breaking?.[1]).toBe('feat');
+    expect(breaking?.[2]).toBe('autocomplete,chip-input');
+  });
+});
+
+describe('the PR title check and the release step', () => {
+  it.each(acceptedHeaders)('agree on $name', ({ header, type }) => {
+    expect(prTitleCheck.test(header)).toBe(true);
+
+    for (const [, opts] of parsingPlugins) {
+      expect(parseHeader(opts, header)).toMatchObject({ type });
+    }
+  });
+
+  it('agree on every scope character the check allows, not a narrower set', () => {
+    // The check's scope is `\([^)]+\)`. A release pattern with a narrower scope class is
+    // what produced #315: the title passed, the commit merged, the release dropped it.
+    const scopes = ['a,b', 'a, b', 'a/b', 'a.b', 'a-b', 'a b', 'a:b', 'a+b', 'a&b', 'a#b', '@scope/pkg'];
+
+    for (const scope of scopes) {
+      const header = `feat(${scope}): a subject`;
+
+      expect(prTitleCheck.test(header)).toBe(true);
+
+      for (const [, opts] of parsingPlugins) {
+        expect(parseHeader(opts, header)).toEqual({
+          type: 'feat',
+          scope,
+          subject: 'a subject',
+        });
+      }
+    }
+  });
+});

package/scripts/release-config/jest.config.ts

@@ -0,0 +1,14 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: '<rootDir>/tsconfig.json',
+    }],
+  },
+  testMatch: ['<rootDir>/**/*.spec.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+};
+
+export default config;

package/scripts/release-config/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "strict": true,
+    "types": ["jest", "node"],
+    "rootDir": ".",
+    "outDir": "../../dist/out-tsc/scripts"
+  },
+  "include": ["**/*.ts"]
+}

package/types/truenas-ui-components.d.ts

@@ -9686,6 +9686,63 @@ declare class TnTableComponent<T = unknown> implements OnInit {
      * full list it holds, and call {@link clearSelection} once a batch action is done.
      */
     selectionKey: _angular_core.InputSignal<((row: T) => unknown) | undefined>;
+    /**
+     * Identifies a row for EXPANSION, so an open detail row survives a `dataSource` change.
+     *
+     * Detail rows are held by object identity, and a consumer that re-fetches hands back new
+     * objects for the same rows — so without a key a background reload closes the row the
+     * user opened, which is usually the moment its contents are worth watching (a running
+     * job's logs, say). With a key set, the table re-points the open rows at the new objects
+     * instead of collapsing them.
+     *
+     * A row the new `data()` does not carry — another page, another tab, filtered out — is
+     * kept, not dropped, and re-opens on its own once that row is listed again. Retention is
+     * unconditional for the same reason it is for {@link selectionKey}: the table sees one
+     * page and cannot tell a row that moved off-screen from one that is gone for good. Call
+     * {@link clearExpansion} when the consumer knows it is gone.
+     *
+     * Without it the table keeps its historical behaviour — any `dataSource` reference change
+     * collapses every open row.
+     *
+     * With a key set, drive expansion through {@link toggleRowExpansion}, {@link expandRow}
+     * and {@link clearExpansion} rather than writing {@link expandedRows} directly, or the
+     * retained set and the visible set drift apart.
+     *
+     * Pass a key that identifies the ROW, not its position, and bind a stable member rather
+     * than writing the function in the template: `[expansionKey]="rowKey"` for a
+     * `rowKey = (row: Job) => row.id` on the host.
+     */
+    expansionKey: _angular_core.InputSignal<((row: T) => unknown) | undefined>;
+    /**
+     * Test id for each ROW, as a function of the row and its index.
+     *
+     * The table writes no id on a `<tr>` of its own, and a cell body is free to be bare
+     * interpolation — `{{ row.username }}` renders no element the consumer can bind to. A list
+     * built that way is unaddressable: an automated suite that has to open, select or delete one
+     * specific row has nothing to select it by but position or cell text, both of which change
+     * under the test. Set this and every row carries `row-<base>` on the `<tr>`, and on its card
+     * in card mode, through the same {@link TnTestIdDirective} as every other id the library
+     * emits — so it honours {@link TN_TEST_ATTR} and is kebab-cased by {@link composeTestId}.
+     *
+     * Pass the base only, not the `row-` prefix, and identify the ROW rather than its position,
+     * the way {@link selectionKey} and {@link expansionKey} do — an index-derived id renames every
+     * row below the one that was deleted. The index is passed for the case where the data genuinely
+     * has nothing unique in it.
+     *
+     * Bind a stable member rather than writing the function in the template, since Angular's
+     * expression grammar has no arrow functions:
+     * `[rowTestId]="rowTestId"` for a `rowTestId = (row: User) => row.username` on the host.
+     *
+     * ```html
+     * <tn-table [dataSource]="users" [rowTestId]="rowTestId" />
+     * <!-- <tr data-testid="row-jane-doe"> -->
+     * ```
+     *
+     * Cells are not covered by this: a suite that has to read one cell of a row still needs an id
+     * on the element that cell renders. Tagging the row is what makes the row itself reachable —
+     * which is the part a consumer cannot add from the outside.
+     */
+    rowTestId: _angular_core.InputSignal<((row: T, index: number) => TnTestIdValue) | undefined>;
     emptyMessage: _angular_core.InputSignal<string>;
     /**
      * Optional second line under `emptyMessage`, for empty states that carry both a headline and an
@@ -9897,12 +9954,25 @@ declare class TnTableComponent<T = unknown> implements OnInit {
     sortColumn: _angular_core.ModelSignal<string>;
     sortDirection: _angular_core.ModelSignal<"" | "desc" | "asc">;
     /**
-     * Set of currently expanded row references.
-     * Note: uses object identity. If the consumer replaces the data array
-     * (e.g. after sorting), expanded state is lost. A future key-based
-     * approach could address this.
+     * The rows of the CURRENT `data()` whose detail row is open, by object identity.
+     *
+     * Replacing the data array collapses everything unless {@link expansionKey} is set, in
+     * which case this is the visible slice of {@link expandedByKey} and survives the swap.
+     *
+     * Writable for consumers that predate {@link expansionKey}. **Adding a key to a consumer
+     * that writes this signal directly is a migration, not a drop-in**: a write here closes
+     * what is on screen but never touches the retained map, so every row whose key is still in
+     * it re-opens on the next reconcile — the one it just closed included. Move those writes to
+     * {@link expandRow}, {@link toggleRowExpansion} and {@link clearExpansion}, which keep the
+     * two in step.
      */
     expandedRows: _angular_core.WritableSignal<Set<unknown>>;
+    /**
+     * Every open detail row keyed by {@link expansionKey}, including rows no longer in
+     * `data()`. Empty (and unused) when no key is set. Holds the row objects so a row that
+     * comes back can be re-pointed at the object the new data carries.
+     */
+    private expandedByKey;
     private static instanceCount;
     private readonly instanceId;
     /**
@@ -9948,6 +10018,16 @@ declare class TnTableComponent<T = unknown> implements OnInit {
     /** True when the layout should keep the table but pin edge columns and scroll. */
     isScrollMode: Signal<boolean>;
     data: Signal<T[]>;
+    /**
+     * The resolved base for each row, by index.
+     *
+     * Computed once per `data()` change rather than called per row per change-detection pass: a
+     * base is usually an array, every call builds a new one, and a new reference restarts the
+     * directive's effect — so binding the call directly would rewrite every row's attribute on
+     * every pass. Recomputing here on the signal the rows are rendered from keeps the value
+     * identical between passes, and correct after a reload hands back new row objects.
+     */
+    protected readonly rowTestIds: Signal<TnTestIdValue[]>;
     effectiveDisplayedColumns: Signal<string[]>;
     /**
      * Every column the table actually renders, including the trailing actions column, which
@@ -9999,6 +10079,26 @@ declare class TnTableComponent<T = unknown> implements OnInit {
      */
     canExpandRow(row: T): boolean;
     toggleRowExpansion(row: T): void;
+    /**
+     * Whether `row`'s detail row counts as open for a toggle. With {@link expansionKey} that is
+     * the retained map, which includes rows this page is not showing; without one it is object
+     * identity against the visible set. Distinct from {@link isRowExpanded}, which drives
+     * rendering and must therefore stay about the row in front of the user.
+     */
+    private isExpansionOpen;
+    /**
+     * Opens `row`'s detail row programmatically — the same thing a chevron click does, for a
+     * consumer restoring expansion from somewhere else (a `?jobId=` query parameter, say).
+     * Honours `singleExpand` and keeps {@link expansionKey}'s retained set in step, which
+     * writing {@link expandedRows} directly does not.
+     */
+    expandRow(row: T): void;
+    /**
+     * Collapses every detail row, including rows retained under {@link expansionKey} that are
+     * not on screen. `expandedRows.set(new Set())` only closes what is visible, so with a key
+     * set the off-screen rows would re-open on the next reconcile.
+     */
+    clearExpansion(): void;
     isRowExpanded(row: T): boolean;
     /**
      * Whether the row element itself acts as the expand/collapse control. Requires `clickable` —
@@ -10226,7 +10326,7 @@ declare class TnTableComponent<T = unknown> implements OnInit {
     getCardLabel(column: string): string;
     getCellValue(row: T, column: string): unknown;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnTableComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnTableComponent<any>, "tn-table", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "displayedColumns": { "alias": "displayedColumns"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; "selectionKey": { "alias": "selectionKey"; "required": false; "isSignal": true; }; "emptyMessage": { "alias": "emptyMessage"; "required": false; "isSignal": true; }; "emptyDescription": { "alias": "emptyDescription"; "required": false; "isSignal": true; }; "emptyIcon": { "alias": "emptyIcon"; "required": false; "isSignal": true; }; "scrollRegionAriaLabel": { "alias": "scrollRegionAriaLabel"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "expandable": { "alias": "expandable"; "required": false; "isSignal": true; }; "bordered": { "alias": "bordered"; "required": false; "isSignal": true; }; "isRowExpandable": { "alias": "isRowExpandable"; "required": false; "isSignal": true; }; "activeRow": { "alias": "activeRow"; "required": false; "isSignal": true; }; "activeWhen": { "alias": "activeWhen"; "required": false; "isSignal": true; }; "activeBg": { "alias": "activeBg"; "required": false; "isSignal": true; }; "activeIndicator": { "alias": "activeIndicator"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "loadingMessage": { "alias": "loadingMessage"; "required": false; "isSignal": true; }; "clickable": { "alias": "clickable"; "required": false; "isSignal": true; }; "expandOnRowClick": { "alias": "expandOnRowClick"; "required": false; "isSignal": true; }; "singleExpand": { "alias": "singleExpand"; "required": false; "isSignal": true; }; "fixedLayout": { "alias": "fixedLayout"; "required": false; "isSignal": true; }; "minColumnWidth": { "alias": "minColumnWidth"; "required": false; "isSignal": true; }; "minWidth": { "alias": "minWidth"; "required": false; "isSignal": true; }; "mobileLayout": { "alias": "mobileLayout"; "required": false; "isSignal": true; }; "cardBreakpoint": { "alias": "cardBreakpoint"; "required": false; "isSignal": true; }; "cardPrimaryCount": { "alias": "cardPrimaryCount"; "required": false; "isSignal": true; }; "sortColumn": { "alias": "sortColumn"; "required": false; "isSignal": true; }; "sortDirection": { "alias": "sortDirection"; "required": false; "isSignal": true; }; }, { "sortChange": "sortChange"; "selectionChange": "selectionChange"; "rowClick": "rowClick"; "rowDoubleClick": "rowDoubleClick"; "sortColumn": "sortColumnChange"; "sortDirection": "sortDirectionChange"; }, ["columnDefs", "detailRowDef", "rowActionsDef"], never, true, [{ directive: typeof TnTestIdDirective; inputs: { "tnTestId": "testId"; }; outputs: {}; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnTableComponent<any>, "tn-table", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "displayedColumns": { "alias": "displayedColumns"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; "selectionKey": { "alias": "selectionKey"; "required": false; "isSignal": true; }; "expansionKey": { "alias": "expansionKey"; "required": false; "isSignal": true; }; "rowTestId": { "alias": "rowTestId"; "required": false; "isSignal": true; }; "emptyMessage": { "alias": "emptyMessage"; "required": false; "isSignal": true; }; "emptyDescription": { "alias": "emptyDescription"; "required": false; "isSignal": true; }; "emptyIcon": { "alias": "emptyIcon"; "required": false; "isSignal": true; }; "scrollRegionAriaLabel": { "alias": "scrollRegionAriaLabel"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "expandable": { "alias": "expandable"; "required": false; "isSignal": true; }; "bordered": { "alias": "bordered"; "required": false; "isSignal": true; }; "isRowExpandable": { "alias": "isRowExpandable"; "required": false; "isSignal": true; }; "activeRow": { "alias": "activeRow"; "required": false; "isSignal": true; }; "activeWhen": { "alias": "activeWhen"; "required": false; "isSignal": true; }; "activeBg": { "alias": "activeBg"; "required": false; "isSignal": true; }; "activeIndicator": { "alias": "activeIndicator"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "loadingMessage": { "alias": "loadingMessage"; "required": false; "isSignal": true; }; "clickable": { "alias": "clickable"; "required": false; "isSignal": true; }; "expandOnRowClick": { "alias": "expandOnRowClick"; "required": false; "isSignal": true; }; "singleExpand": { "alias": "singleExpand"; "required": false; "isSignal": true; }; "fixedLayout": { "alias": "fixedLayout"; "required": false; "isSignal": true; }; "minColumnWidth": { "alias": "minColumnWidth"; "required": false; "isSignal": true; }; "minWidth": { "alias": "minWidth"; "required": false; "isSignal": true; }; "mobileLayout": { "alias": "mobileLayout"; "required": false; "isSignal": true; }; "cardBreakpoint": { "alias": "cardBreakpoint"; "required": false; "isSignal": true; }; "cardPrimaryCount": { "alias": "cardPrimaryCount"; "required": false; "isSignal": true; }; "sortColumn": { "alias": "sortColumn"; "required": false; "isSignal": true; }; "sortDirection": { "alias": "sortDirection"; "required": false; "isSignal": true; }; }, { "sortChange": "sortChange"; "selectionChange": "selectionChange"; "rowClick": "rowClick"; "rowDoubleClick": "rowDoubleClick"; "sortColumn": "sortColumnChange"; "sortDirection": "sortDirectionChange"; }, ["columnDefs", "detailRowDef", "rowActionsDef"], never, true, [{ directive: typeof TnTestIdDirective; inputs: { "tnTestId": "testId"; }; outputs: {}; }]>;
 }
 
 /**
@@ -10431,6 +10531,17 @@ declare class TnTableHarness extends ComponentHarness {
      * @returns Promise resolving to true if the loading overlay is visible.
      */
     isLoading(): Promise<boolean>;
+    /**
+     * Gets the test id written on a data row by `[rowTestId]`.
+     *
+     * Layout-aware, like the rest of the row queries: reads the card in the card layout, which
+     * carries the same id. Reads `data-testid` first and falls through to `data-test`, so it
+     * answers the same either way the consumer configured `TN_TEST_ATTR`.
+     *
+     * @param rowIndex Zero-based index of the data row (or card).
+     * @returns Promise resolving to the row's test id, or null when `[rowTestId]` is unset.
+     */
+    getRowTestId(rowIndex: number): Promise<string | null>;
     /**
      * Checks if a data row is currently marked active.
      *