@truenas/ui-components 0.5.3 → 0.6.1

package/package.json

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

package/scripts/harness-docs/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/harness-docs/markdown-table.spec.ts

@@ -0,0 +1,151 @@
+import {
+  escapeTableCell,
+  METHOD_TABLE_HEADER,
+  methodTableRow,
+  PROPERTY_TABLE_HEADER,
+  propertyTableRow,
+} from './markdown-table';
+
+/**
+ * Count the cells a Markdown parser reads out of one table row.
+ *
+ * The leading and trailing `|` are the row's own fences rather than delimiters, and a
+ * backslash-escaped `\|` is content — which is exactly the distinction under test, so it
+ * is spelled out here rather than borrowed from the code being tested.
+ */
+function cellsIn(row: string): number {
+  const trimmed = row.trim();
+
+  return trimmed.slice(1, -1).split(/(?<!\\)\|/).length;
+}
+
+/** The header's own first line decides how many cells every row below it must have. */
+const columnsOf = (header: string): number => cellsIn(header.split('\n')[0]);
+
+describe('escapeTableCell', () => {
+  it('escapes a pipe so it cannot end the cell', () => {
+    expect(escapeTableCell('string | RegExp')).toBe('string \\| RegExp');
+  });
+
+  it('escapes every pipe, not just the first', () => {
+    expect(escapeTableCell(`'asc' | 'desc' | '' | null`)).toBe(
+      `'asc' \\| 'desc' \\| '' \\| null`
+    );
+  });
+
+  it('uses the backslash escape rather than an HTML entity, which a code span would show literally', () => {
+    expect(escapeTableCell('A | B')).not.toContain('&#124;');
+  });
+
+  it('collapses newlines, because a row is one line', () => {
+    expect(escapeTableCell('first line\n  second line')).toBe('first line second line');
+  });
+
+  it('leaves a value with nothing to escape alone', () => {
+    expect(escapeTableCell('Promise<void>')).toBe('Promise<void>');
+  });
+});
+
+describe('methodTableRow', () => {
+  const columns = columnsOf(METHOD_TABLE_HEADER);
+
+  it('has a four-column header', () => {
+    expect(columns).toBe(4);
+  });
+
+  it('builds one row per union-typed parameter list, not one per union member', () => {
+    const row = methodTableRow({
+      name: 'clickActionButton',
+      parameters: 'string | RegExp',
+      returnType: 'Promise<void>',
+      description: 'Clicks an action button in the dialog footer by its label.',
+    });
+
+    expect(cellsIn(row)).toBe(columns);
+  });
+
+  it('keeps the row intact when the union is in the return type', () => {
+    const row = methodTableRow({
+      name: 'getPlaceholder',
+      parameters: '',
+      returnType: 'Promise<string | null>',
+      description: 'Gets the placeholder text of the input.',
+    });
+
+    expect(cellsIn(row)).toBe(columns);
+  });
+
+  it('keeps the row intact when the parameters and the return type both carry unions', () => {
+    const row = methodTableRow({
+      name: 'getCardSortDirection',
+      parameters: `number, 'enter' | 'space'`,
+      returnType: `Promise<'asc' | 'desc' | '' | null>`,
+      description: 'Gets the active sort direction in the card layout.',
+    });
+
+    expect(cellsIn(row)).toBe(columns);
+  });
+
+  it('keeps the row intact when the description itself contains a pipe', () => {
+    const row = methodTableRow({
+      name: 'getType',
+      parameters: '',
+      returnType: 'Promise<string>',
+      description: 'Reads the native type: button | submit | reset.',
+    });
+
+    expect(cellsIn(row)).toBe(columns);
+  });
+
+  it('puts the description in the Description column', () => {
+    const row = methodTableRow({
+      name: 'clickAction',
+      parameters: 'string | RegExp',
+      returnType: 'Promise<void>',
+      description: "Clicks one of the banner's actions by its label.",
+    });
+    const cells = row.trim().slice(1, -1).split(/(?<!\\)\|/);
+
+    expect(cells[3].trim()).toBe("Clicks one of the banner's actions by its label.");
+  });
+
+  it('leaves the Parameters cell empty for a method that takes none', () => {
+    const row = methodTableRow({
+      name: 'getText',
+      parameters: '',
+      returnType: 'Promise<string>',
+      description: 'Gets the text.',
+    });
+    const cells = row.trim().slice(1, -1).split(/(?<!\\)\|/);
+
+    expect(cells[1].trim()).toBe('');
+  });
+});
+
+describe('propertyTableRow', () => {
+  const columns = columnsOf(PROPERTY_TABLE_HEADER);
+
+  it('has a three-column header', () => {
+    expect(columns).toBe(3);
+  });
+
+  it('builds one row per union-typed property', () => {
+    const row = propertyTableRow({
+      name: 'label',
+      type: 'string | RegExp',
+      description: "Filters by the action's label text.",
+    });
+
+    expect(cellsIn(row)).toBe(columns);
+  });
+
+  it('keeps the row intact when the description contains a pipe', () => {
+    const row = propertyTableRow({
+      name: 'orientation',
+      type: 'string',
+      description: 'One of horizontal | vertical.',
+    });
+
+    expect(cellsIn(row)).toBe(columns);
+  });
+});

package/scripts/harness-docs/markdown-table.ts

@@ -0,0 +1,77 @@
+/**
+ * Markdown table rows for the harness documentation `scripts/generate-harness-docs.ts`
+ * generates.
+ *
+ * These live apart from the generator because that file calls `main()` at the bottom of
+ * the module, so importing anything out of it runs the whole build. Everything here is a
+ * pure function of its argument, which is what makes the row shape testable at all.
+ */
+
+/** A harness method, reduced to the fields a table row renders. */
+export interface MethodRowInput {
+  name: string;
+  parameters: string;
+  returnType: string;
+  description: string;
+}
+
+/** An interface property, reduced to the fields a table row renders. */
+export interface PropertyRowInput {
+  name: string;
+  type: string;
+  description: string;
+}
+
+/** Header and delimiter rows for the Methods table. Four columns. */
+export const METHOD_TABLE_HEADER =
+  '| Method | Parameters | Returns | Description |\n' +
+  '|--------|------------|---------|-------------|\n';
+
+/** Header and delimiter rows for an interface's properties table. Three columns. */
+export const PROPERTY_TABLE_HEADER =
+  '| Property | Type | Description |\n' +
+  '|----------|------|-------------|\n';
+
+/**
+ * Render one value as the contents of a Markdown table cell.
+ *
+ * A `|` is a cell delimiter wherever it appears in a table row, and a code span does not
+ * protect it: the row is split into cells before its inline content is parsed, so a
+ * `string | RegExp` parameter arrives as two cells and every column after it shifts left
+ * by one. That is what dropped the Description column of every union-typed harness
+ * method.
+ *
+ * The backslash escape is read during that split, which is why `\|` works inside a code
+ * span and `|` does not — an entity inside a code span renders as the six literal
+ * characters that spell it.
+ *
+ * Newlines collapse for the same reason: a row is one line, so a wrapped type or
+ * description would otherwise end the table partway through.
+ */
+export function escapeTableCell(value: string): string {
+  return value
+    .replace(/\s*\n+\s*/g, ' ')
+    .trim()
+    .replace(/\|/g, '\\|');
+}
+
+/** One row of the Methods table, newline included. */
+export function methodTableRow(method: MethodRowInput): string {
+  const parameters = method.parameters ? `\`${escapeTableCell(method.parameters)}\`` : '';
+
+  return (
+    `| \`${escapeTableCell(method.name)}()\`` +
+    ` | ${parameters}` +
+    ` | \`${escapeTableCell(method.returnType)}\`` +
+    ` | ${escapeTableCell(method.description)} |\n`
+  );
+}
+
+/** One row of an interface's properties table, newline included. */
+export function propertyTableRow(property: PropertyRowInput): string {
+  return (
+    `| \`${escapeTableCell(property.name)}\`` +
+    ` | \`${escapeTableCell(property.type)}\`` +
+    ` | ${escapeTableCell(property.description)} |\n`
+  );
+}

package/scripts/harness-docs/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/scripts/jest.config.ts

@@ -0,0 +1,18 @@
+import type { Config } from 'jest';
+
+/**
+ * `yarn test:scripts` — every build script under this directory that has tests.
+ *
+ * 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.
+ */
+const config: Config = {
+  projects: [
+    '<rootDir>/harness-docs/jest.config.ts',
+    '<rootDir>/icon-sprite/jest.config.ts',
+  ],
+};
+
+export default config;