@harmolody/ui 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @harmolody/ui
+
+Tailwind-first Angular 22.2 dynamic forms and data tables, extracted from Harmolody Admin. Built with standalone components, signal inputs/outputs, Reactive Forms, and OnPush change detection.
+
+Install the package into a compatible Angular 22.2+ app. Source and full examples: [codibyte-co/harmolody-ui](https://github.com/codibyte-co/harmolody-ui).
+
+```sh
+npm install @harmolody/ui
+npm install tailwindcss @tailwindcss/postcss postcss
+```
+
+Enable the PostCSS plugin in `.postcssrc.json`:
+
+```json
+{ "plugins": { "@tailwindcss/postcss": {} } }
+```
+
+In global `src/styles.css`:
+
+```css
+@import 'tailwindcss';
+@import '@harmolody/ui/theme.css';
+@source '../node_modules/@harmolody/ui';
+```
+
+Adjust `@source` relative to your CSS file. It is required to generate utilities used by the installed library.
+
+```ts
+import {
+  DynamicFormComponent,
+  TableComponent,
+  type FormConfig,
+  type TableConfig,
+} from '@harmolody/ui';
+```
+
+```html
+<hui-dynamic-form #form [config]="formConfig" (formSubmit)="save($event); form.finishSubmit()" />
+<hui-table [config]="tableConfig" />
+```
+
+Import both components in the host's `imports`. For async submissions, call `finishSubmit()` after completion, including failure paths. Static forms require no providers. API-backed fields need `provideHttpClient()`; internal table links need `provideRouter(routes)`. The table emits sorting/pagination events; the host supplies sorted/page data. Use `TableCellDirective` and `huiTableCell` for custom cells, and `provideHarmolodyUi()` for optional translations, icon overrides, and media selection.
+
+Theme variables use `--hui-*` (for example `--hui-primary`, `--hui-surface`, `--hui-border`). The workspace includes complete guides, a working showcase, and unit/browser/packed-consumer verification. Detailed guides ship under `docs/` in the package.
+
+License: `UNLICENSED`; no open-source license is granted.

package/docs/admin-migration.md

@@ -0,0 +1,56 @@
+# Adopt in Harmolody Admin
+
+The extraction leaves `harmolody_admin` unchanged. Migrate one feature first, then replace imports gradually. The current admin starts at Angular 22.1.x; this library targets 22.2.1, so align its Angular/CLI/compiler versions before installing.
+
+1. Build and pack this workspace: `npm run pack`.
+2. In the admin, install `../harmolody_ui/artifacts/harmolody-ui-0.1.0.tgz`.
+3. Add `@source '../node_modules/@harmolody/ui';` in the admin's global CSS. If retaining the existing semantic Tailwind theme, map existing colors to `--hui-*` variables or integrate the library's theme carefully to avoid duplicate semantic definitions.
+4. Replace shared component imports with package imports. Keep config names and Reactive Forms behavior. Rename selectors and the cell directive.
+5. Supply localization/media adapters using host services in a provider factory; configure explicit table link generators.
+6. Run the admin's existing tests and production build, inspect real dialogs and data pages, then remove old shared files only after all consumers migrate.
+
+| Old                                       | Package equivalent                              |
+| ----------------------------------------- | ----------------------------------------------- |
+| `@shared/components/form-builder`         | `@harmolody/ui`                                 |
+| `@shared/components/table`                | `@harmolody/ui`                                 |
+| `@shared/components/forms`                | Supporting control exports from `@harmolody/ui` |
+| `<app-dynamic-form>`                      | `<hui-dynamic-form>`                            |
+| `<app-table>`                             | `<hui-table>`                                   |
+| `appTableCell`                            | `huiTableCell`                                  |
+| `<app-table-column-selector>`             | `<hui-table-column-selector>`                   |
+| Implicit artist/user/etc. route discovery | Column `linkGenerator` callback                 |
+| Built-in admin media dialog               | Host `selectMedia` adapter                      |
+
+For Angular DI integrations:
+
+```ts
+import { inject } from '@angular/core';
+import { HARMOLODY_UI_CONFIG, HARMOLODY_MEDIA_SELECTOR } from '@harmolody/ui';
+
+providers: [
+  {
+    provide: HARMOLODY_UI_CONFIG,
+    useFactory: () => {
+      const localization = inject(LocalizationService); // Your admin service
+      return {
+        translate: (text: string, params?: Record<string, string | number>) =>
+          localization.translate(text, params),
+      };
+    },
+  },
+  {
+    provide: HARMOLODY_MEDIA_SELECTOR,
+    useFactory: () => {
+      const dialog = inject(DialogService); // Your admin service
+      return async (request: MediaSelectorRequest) => {
+        const result = await dialog.open(MediaSelectorDialogComponent, dialogOptions, request);
+        return result.action === 'confirm' ? result.data.fileUrl : undefined;
+      };
+    },
+  },
+];
+```
+
+The example assumes your existing dialog contract and imports; adapt options to the admin implementation. Do not additionally call `provideHarmolodyUi()` after these token providers because it would replace them.
+
+Behavior changes to review: validation is restored when conditional required fields reappear; submission remains locked until `finishSubmit()`; configured disabled fields stay disabled afterwards; column selector bulk actions preserve pinned columns. These fixes live only in the extracted package. Initial record replacement and general schema removal still require a new form instance.

package/docs/dynamic-form.md

@@ -0,0 +1,116 @@
+# Dynamic form
+
+```ts
+import { DynamicFormComponent, type FormConfig, type FieldConfig } from '@harmolody/ui';
+```
+
+Import `DynamicFormComponent` in a standalone component and render `<hui-dynamic-form>`. `config` is required; `initialValues` is an optional object applied when the component is created. Treat a form instance as one schema and one edit session: recreate it for a different record or substantially different schema. Adding fields to `config` is supported without losing existing values; deleting controls or replacing validators through a new schema is not a general schema reconciliation API.
+
+## Fields
+
+Supported types: `text`, `email`, `password`, `number`, `tel`, `url`, `textarea`, `select`, `radio`, `checkbox`, `switch`, `autocomplete`, `search`, `date`, `datetime`, `month`, `year`, `file`, `image-selector`, `array`.
+
+| Property                                                     | Meaning                                                                                                      |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `key`, `label`, `type`                                       | Stable flat control key, accessible label, control type                                                      |
+| `defaultValue`, `required`, `disabled`, `hidden`             | Initial state; disabled values still appear in submitted raw values                                          |
+| `placeholder`, `hint`, `helper`, `description`, `note`       | Supporting text; notes support `noteVariant`                                                                 |
+| `validation`                                                 | `required`, `email`, `minLength`, `maxLength`, `min`, `max`, `pattern`, `custom` rules                       |
+| `options`                                                    | `{label, value, disabled?}` items for choices                                                                |
+| `multiple`, `searchable`, `optionPresentation`, `chipLayout` | Multiple choices, dropdown search, dropdown/chips, inline/wrap chips                                         |
+| `optionsFromApi`                                             | GET/POST option source; needs host `provideHttpClient()`                                                     |
+| `dependsOn`                                                  | `{field, clearOnChange?, refreshOn?}` or an array of dependencies                                            |
+| `showWhen`, `hideWhen`                                       | `{field, operator, value?, values?}` or an array; `showWhen` conditions combine with AND, `hideWhen` with OR |
+| `fullWidth`, `columnSpan`, `containerClass`, `cssClass`      | Grid positioning and custom classes; grid supports 1–3 columns                                               |
+| `min`, `max`, `step`, `rows`, `minDate`, `maxDate`           | Number, textarea, date constraints                                                                           |
+| `accept`, `multiple`, `maxSize`, `maxFiles`                  | File selection constraints; values are local file metadata, uploading belongs to the host                    |
+| `arrayFields`, `minItems`, `maxItems`, `itemLabel`           | Repeating groups and bounds; `itemLabel` accepts `{index}`                                                   |
+
+Email and numeric fields get corresponding validators automatically. Register custom validators before rendering via `inject(FormBuilderService).registerCustomValidator('uniqueName', validatorFn)` and reference the name in `{type: 'custom', validator: 'uniqueName'}`. Rule `message` is retained in the model but the current field error display uses the built-in error formatter; custom rule messages are not a guaranteed override.
+
+```ts
+const config: FormConfig = {
+  layout: 'grid',
+  columns: 2,
+  fieldLayout: 'column',
+  validationStrategy: 'submit',
+  fieldsets: [{ key: 'profile', legend: 'Profile', fields: ['name', 'genre'] }],
+  fields: [
+    { key: 'name', label: 'Name', type: 'text', required: true },
+    { key: 'genre', label: 'Genre', type: 'select', options: [{ label: 'Folk', value: 'folk' }] },
+    { key: 'active', label: 'Active', type: 'switch', defaultValue: false },
+    {
+      key: 'website',
+      label: 'Website',
+      type: 'url',
+      required: true,
+      showWhen: { field: 'active', operator: 'eq', value: true },
+    },
+    {
+      key: 'credits',
+      label: 'Credits',
+      type: 'array',
+      maxItems: 5,
+      arrayFields: [{ key: 'name', label: 'Credit name', type: 'text', required: true }],
+    },
+  ],
+  submitButton: { label: 'Save' },
+  showCancelButton: { hidden: true },
+};
+```
+
+`fieldLayout: 'row'` places labels beside controls on wider screens. Fieldsets group presentation while values remain flat. Fields outside fieldsets appear afterwards. Hidden fields keep their values and have validation suspended; visible fields regain validators.
+
+## Inputs, outputs, methods
+
+| API                                         | Payload / behavior                                                                          |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `config`, `initialValues`                   | Form schema and initial record                                                              |
+| `formSubmit`                                | Valid raw values; disables form and holds submit state until `finishSubmit()`               |
+| `valueChange`                               | Current enabled control values                                                              |
+| `fieldChange`                               | `{values, selectedObjects}` when a choice field has `emitSelectedObject: true`              |
+| `reset`, `cancel`                           | Void events                                                                                 |
+| `actionClick`                               | `{action, formValue, isValid}` for a custom button action                                   |
+| `fieldActionClick`                          | `{fieldKey, formValue}` for a choice field action                                           |
+| `finishSubmit()`                            | Releases submission lock, restores configured disabled controls                             |
+| `validate()`                                | Shows errors and returns validity                                                           |
+| `getRawValue<T>()`                          | Reads all values, including disabled controls                                               |
+| `setFieldValue(key, value)`                 | Programmatic field update                                                                   |
+| `getField(key)`                             | Gets a rendered dynamic field                                                               |
+| `reloadFieldOptions(key)`                   | Reloads a field's API options; set `cache: false` for fresh requests                        |
+| `reloadFieldOptionsAndSetValue(key, value)` | Legacy convenience method; uses a 500ms delay and should not be relied on for slow requests |
+
+```ts
+async save(values: Record<string, unknown>): Promise<void> {
+  try {
+    await this.repository.save(values);
+  } finally {
+    this.form().finishSubmit();
+  }
+}
+```
+
+Built-in Cancel, Reset, Submit buttons appear unless individually hidden. The default Submit button is disabled while invalid. Use a custom submit action without `disableOnInvalid` to allow users to attempt submission and display validation errors. `actions` replaces them with buttons ordered by `order`; `type: 'submit'` and `'reset'` use the standard handlers. Other buttons emit `actionClick`. Variants: `primary`, `secondary`, `outline`, `danger`, `success`, `link`. The reset method clears current values; it does not restore the original record.
+
+## API-backed options
+
+```ts
+// Host application providers
+provideHttpClient()
+
+// FormConfig
+apiConfig: { baseUrl: 'https://api.example.com' },
+fields: [{
+  key: 'artistId', label: 'Artist', type: 'autocomplete',
+  optionsFromApi: {
+    url: '/artists', method: 'GET', searchParam: 'query', cache: false,
+    map: { data: 'items', label: 'name', value: 'id' },
+    dynamicFilters: [{ field: 'genreId', operator: 'eq', valueFrom: 'genreId', whenNotEmpty: true }],
+  },
+  dependsOn: { field: 'genreId', clearOnChange: true },
+}]
+```
+
+Use host HTTP interceptors for authentication. Field `baseUrl` overrides the form URL. GET filters become query parameters; POST filters stay in a `filters` array. Request/response transform callbacks support other backend shapes. Cache keys include API configuration, headers, and mapping; `OptionsLoaderService.clearCache(url?)` clears all or matching URL entries. Failed requests currently produce empty options and log an error; the host owns notifications and retry policy. Static forms require no HTTP provider.
+
+Nested arrays inside `arrayFields` are not supported as a recursive array builder. Most initial schema properties are construction-time settings. Properties such as named `onChange`/`onBlur` strings are legacy metadata; handle the emitted Angular events instead. Per-field `emitSelectedObject` controls `fieldChange`; do not rely on the legacy global `emitSelectedObjects` flag alone.

package/docs/publishing.md

@@ -0,0 +1,56 @@
+# Publishing @harmolody/ui
+
+The public package name is `@harmolody/ui`; source is hosted at https://github.com/codibyte-co/harmolody-ui. npm and GitHub permissions are managed separately. The publishing npm account must have write access to the `@harmolody` scope.
+
+The package keeps `UNLICENSED`, reserving rights rather than granting an open-source license. Repository links, declarations, partial Angular compilation, Tailwind theme exports, usage documentation, and an explicit package file list are included.
+
+## Authenticate
+
+```sh
+npm login --registry https://registry.npmjs.org
+npm whoami --registry https://registry.npmjs.org
+```
+
+Complete browser login or two-factor verification directly with npm when prompted. Do not commit npm tokens or credentials.
+
+## Validate and preview a release
+
+```sh
+npm ci
+npm run release:check
+```
+
+This runs unit tests, production builds, tarball generation, an independent consumer installation/build, and an npm publish dry run. It uploads nothing. For browser checks also run `npm run test:e2e`; install Chromium with `npx playwright install chromium`, or use `PLAYWRIGHT_CHANNEL=chrome` with installed Google Chrome.
+
+## Publish
+
+```sh
+npm run publish:npm
+```
+
+The command validates first, then publishes only `dist/ui` with public access to https://registry.npmjs.org. The root workspace is private. npm may require two-factor/browser approval; complete the CLI prompt. Publishing a version is permanent: the same name/version cannot be published again.
+
+## Next versions
+
+```sh
+npm version patch --prefix projects/ui --no-git-tag-version
+# Update CHANGELOG.md, then validate and commit the source
+npm run release:check
+git add .
+git commit -m "Release next version"
+git push origin main
+npm run publish:npm
+```
+
+Use minor/major increments intentionally for new features or breaking APIs. Choose a patch version higher than the registry version if a release already exists. The authoritative version is `projects/ui/package.json`; building copies it into `dist/ui`.
+
+## Verify the published package
+
+```sh
+npm view @harmolody/ui version --registry https://registry.npmjs.org
+npm install @harmolody/ui
+```
+
+Consumers must add the Tailwind theme import and source registration described in the README. The metadata links the npm package to GitHub; it does not configure GitHub Actions or automatic publishing. A future CI workflow can use npm trusted publishing after configuring the repository/workflow relationship on npm.
+
+References: [scoped public publishing](https://docs.npmjs.com/creating-and-publishing-scoped-public-packages/), [trusted publishing](https://docs.npmjs.com/trusted-publishers/).

package/docs/styling-and-adapters.md

@@ -0,0 +1,77 @@
+# Styling and application adapters
+
+## Tailwind 4
+
+Use these imports in the consumer's global `src/styles.css`:
+
+```css
+@import 'tailwindcss';
+@import '@harmolody/ui/theme.css';
+@source '../node_modules/@harmolody/ui';
+```
+
+Install `tailwindcss`, `@tailwindcss/postcss`, `postcss` and enable the PostCSS plugin as shown in the root README. The library is intentionally Tailwind-first. The package includes an uncompiled theme entry point and utility classes in its compiled Angular templates; your app generates the utilities. Importing only the theme will not generate all the classes unless the package source is registered.
+
+## Theme tokens
+
+Override `--hui-*` CSS variables on `:root` or on a container surrounding the components:
+
+```css
+:root {
+  --hui-primary: #2563eb;
+  --hui-primary-foreground: #ffffff;
+  --hui-background: #f8fafc;
+  --hui-surface: #ffffff;
+  --hui-border: #cbd5e1;
+}
+[data-theme='dark'] {
+  --hui-background: #0e0b16;
+  --hui-surface: #151225;
+  --hui-surface-hover: #1f1b2e;
+  --hui-foreground: #f9fafb;
+  --hui-text-secondary: #cbd5e1;
+  --hui-text-muted: #94a3b8;
+  --hui-muted: #1f1b2e;
+  --hui-border: #2a2540;
+  color-scheme: dark;
+}
+```
+
+Available tokens: `background`, `background-soft`, `surface`, `surface-hover`, `foreground`, `primary`, `primary-foreground`, `primary-soft`, `muted`, `text-secondary`, `text-muted`, `text-disabled`, `border`, `destructive`, all prefixed `--hui-`. Semantic utilities such as `bg-surface`, `text-primary`, `border-border` resolve through these tokens. Theme imports define global semantic utility names; review overlaps with an existing app theme. Some extracted controls retain explicit violet utility classes from the admin; token overrides do not recolor every legacy control. Extend with host classes where necessary. The package does not switch dark mode automatically.
+
+## Optional providers
+
+Basic static forms and tables work without `provideHarmolodyUi()`. English labels and built-in icons are defaults. Configure application integrations in `app.config.ts`:
+
+```ts
+import { provideHarmolodyUi } from '@harmolody/ui';
+import { provideHttpClient } from '@angular/common/http';
+import { provideRouter } from '@angular/router';
+
+providers: [
+  provideHttpClient(), // Required only for API-backed options
+  provideRouter(routes), // Required for internal table links
+  provideHarmolodyUi({
+    translate: (text, parameters) => myTranslator.translate(text, parameters),
+    icons: {
+      'custom-star': {
+        path: 'M12 2l3 7 7 1-5 5 1 7-6-4-6 4 1-7-5-5 7-1z',
+        fill: 'currentColor',
+        stroke: 'none',
+      },
+    },
+    selectMedia: async ({ mediaType, allowUpload }) => {
+      const result = await myMediaDialog.open({ mediaType, allowUpload });
+      return result.confirmed ? result.fileUrl : undefined;
+    },
+  }),
+];
+```
+
+These are example host services, not imports provided by the package. Create the adapter inside a provider factory if your application integration needs Angular `inject()`; do not call `inject()` later inside an async callback outside an injection context.
+
+Localization receives the original label and optional interpolation parameters. Without an adapter, `{count}` style placeholders are interpolated. Translation callbacks should read the host's language signal if labels need to react to language changes.
+
+Icon overrides use the built-in `SvgIcon` structure (`path`, `viewBox?`, `stroke?`, `fill?`, `strokeWidth?`). Icons without an explicit `ariaLabel` are decorative and hidden from assistive technology; supply `ariaLabel` for meaningful standalone icons. Definitions override same-name built-ins; missing names yield no SVG. Avoid accepting untrusted SVG definitions as configuration.
+
+Media selection returns a URL string for selection, `null` for clearing, and `undefined` for cancellation. The Browse button is disabled without a media adapter; `editableInput: true` supports direct URL entry. Storage, uploads, authentication, and dialogs belong to the host project.

package/docs/table.md

@@ -0,0 +1,93 @@
+# Table
+
+```ts
+import {
+  TableComponent,
+  TableCellDirective,
+  TableColumnSelectorComponent,
+  type TableConfig,
+  type TableColumn,
+  type TableSort,
+} from '@harmolody/ui';
+```
+
+`<hui-table [config]="config()" />` renders the supplied rows. **The table emits sorting and pagination requests; the host sorts, fetches, and slices data.** It does not silently paginate or sort the provided array. The showcase demonstrates client-side handling; server-driven projects can pass a page returned by their API.
+
+```ts
+interface Artist {
+  id: string;
+  name: string;
+  active: boolean;
+}
+const config: TableConfig<Artist> = {
+  rowKey: 'id',
+  columns: [
+    { key: 'name', label: 'Artist', sortable: true },
+    { key: 'active', label: 'Status', type: 'template' },
+  ],
+  data: [{ id: '1', name: 'May', active: true }],
+  pagination: { page: 1, pageSize: 10, total: 48, pageSizeOptions: [10, 20, 50] },
+  selection: { mode: 'multiple', selectedRows: [] },
+  actions: [{ label: 'Edit', icon: 'edit', onClick: (row) => console.log(row.id) }],
+  stickyHeader: true,
+  maxHeight: '480px',
+  hoverable: true,
+};
+```
+
+## Custom cells
+
+```html
+<hui-table [config]="config()">
+  <ng-template huiTableCell="active" let-value let-row="row" let-index="index" let-column="column">
+    <span>{{ row.active ? 'Active' : 'Draft' }}</span>
+  </ng-template>
+</hui-table>
+```
+
+Import `TableCellDirective` alongside the table. Template context: `$implicit` cell value, `row`, `index`, `column`. You can also supply `column.template` or render a standalone component with `type: 'component'`, `component`, and `componentInputs`.
+
+## Configuration
+
+| Property                                                        | Behavior                                                                                  |
+| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `columns`, `data`                                               | Visible columns and currently displayed rows                                              |
+| `rowKey`                                                        | Stable property or `(row) => string \| number`; always provide it for selection/reorder   |
+| `sort`                                                          | Controlled `{column, direction: 'asc' \| 'desc' \| null}`                                 |
+| `pagination`                                                    | 1-based page, page size, total record count                                               |
+| `selection`                                                     | `none`, `single`, `multiple`; selected row objects from current page                      |
+| `actions`                                                       | Label/icon/callback, `hidden(row)`, `disabled(row)`, variant, submenu, divider            |
+| `loading`, `emptyMessage`                                       | Loading and empty states                                                                  |
+| `stickyHeader`, `maxHeight`                                     | Sticky header, 600px default max height; disable sticky for natural page layout           |
+| `showHeader`, `showHeaderOnlyOnScroll`                          | Header visibility options                                                                 |
+| `bordered`, `striped`, `hoverable`, `compact`, `showRowNumbers` | Presentation                                                                              |
+| `rowReorder`                                                    | `{enabled, disabled?, onDisabledAttempt?, onReorder?}`; emits reordered current-page rows |
+| `rowClass`, `onRowClick`                                        | Custom row classes and click handler                                                      |
+
+Column options: dotted `key` lookup (e.g. `profile.name`), `label`, `sortable`, `align`, `headerAlign`, `width`, `type` (`text`, `image`, `icon`, `link`, `component`, `template`), `render(value, row, index)`, `cellClass`, `hideable`, `hideOnScreens`. Image columns support fallback and classes; icon columns accept static or callback names/classes/labels. Render callbacks produce text, not raw HTML.
+
+Links are explicit: use `linkGenerator(row)`, optional `linkTarget`, and `onClick(row)`. Internal links use Angular Router; configure `provideRouter(routes)` in the host when using them. The extracted library no longer guesses Harmolody entity routes from column names.
+
+## Events
+
+| Output            | Payload                                                      |
+| ----------------- | ------------------------------------------------------------ |
+| `sortChange`      | `{column, direction}`; cycles ascending, descending, cleared |
+| `pageChange`      | Requested 1-based page                                       |
+| `pageSizeChange`  | Requested size; host resets page to 1                        |
+| `selectionChange` | Selected displayed row objects                               |
+| `rowReorder`      | `{row, previousIndex, currentIndex, data}`                   |
+
+Equivalent config callbacks are also supported (`onSort`, `onPageChange`, `onPageSizeChange`, selection `onSelectionChange`, reorder `onReorder`). Choose outputs or callbacks for a given action to avoid duplicate API requests. Update config and data immutably because components use OnPush and signals. Selection is page-local; manage cross-page selection in the host. Sorting headers support Enter/Space and expose `aria-sort`.
+
+## Column selector
+
+```html
+<hui-table-column-selector
+  [allColumns]="columns"
+  [visibleColumnKeys]="visibleKeys()"
+  (visibleColumnsChange)="visibleKeys.set($event)"
+/>
+```
+
+Filter the table's `columns` using `visibleKeys`. `hideable: false` pins a column. The component never persists preferences automatically; the host may save keys in its user settings.

package/docs/testing.md

@@ -0,0 +1,22 @@
+# Validation
+
+```sh
+npm ci
+npm run build:lib
+npm test
+npm run build:example
+npm run pack
+npm run check:package
+npx playwright install chromium
+npm run test:e2e
+```
+
+Library unit tests cover existing form controls, array initialization, config additions, options loading, choice presentations, actions, custom table cells, and row reordering. Additional extraction tests cover application adapters, conditional validation, submission locking, and disabled fields. The showcase unit test consumes `dist/ui` through `@harmolody/ui`; build the library first.
+
+Browser tests exercise actual invalid and valid submissions, keyboard sorting, page changes, selection, row actions, themes, responsive layout, and computed Tailwind grid styles.
+
+`scripts/check-package.mjs` creates a temporary consumer workspace outside this repository, installs the tarball using its own `node_modules`, and compiles an Angular app with Tailwind scanning the **installed npm package**. This catches exports, template compilation, peers, and theme/source packaging errors that workspace aliases can hide. The temporary consumer is retained and its path printed for inspection.
+
+The package checker runs an installation and production build; it requires registry access and a supported Node version. It does not publish. Browser checks use Playwright Chromium; install it once with the command above. No backend credentials are needed.
+
+On a machine with Google Chrome installed, you can skip the Playwright Chromium download and use `PLAYWRIGHT_CHANNEL=chrome npm run test:e2e`. The default uses Playwright's downloaded Chromium. In restrictive macOS sandboxes, Angular's native Tailwind compilation and headless browser launch may require running these checks in a normal terminal.