@hawiyah/angular 0.0.0-stage → 0.2.1

package/dist/README.md

@@ -0,0 +1,335 @@
+# @hawiyah/angular
+
+Angular components for Hawiyah — هوية, a UI library built to comply with the DGA
+Platforms Code. Install with `npm install @hawiyah/styles @hawiyah/angular`. This is a
+pre-1.0 release, so a minor version may still change its API.
+
+The 77 catalog entries render native HTML with Angular templates. There are no
+custom-element wrappers, schemas, runtime HTML injection, or framework renderers
+inside core. Angular owns state and DOM; the shared core supplies pure combobox
+transitions and keyboard navigation. Shared `hw-` classes provide appearance.
+
+## Use
+
+Build the workspace packages before starting the example. Import the standalone
+components you use. The library builds with `ng-packagr` to Angular Package Format
+(partial compilation); production Angular applications link it through their
+normal Angular AOT build.
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HwTextFieldComponent, HwComboboxComponent, HwButtonDirective } from '@hawiyah/angular';
+
+@Component({
+  standalone: true,
+  imports: [FormsModule, HwTextFieldComponent, HwComboboxComponent, HwButtonDirective],
+  template: `
+    <form #form="ngForm" (ngSubmit)="save()">
+      <hw-text-field controlId="name" label="Name" name="name" [(ngModel)]="name" [required]="true" />
+      <hw-combobox controlId="city" label="City" name="city" [(ngModel)]="city" [options]="cities" />
+      <button hwButton type="submit">Save</button>
+      <button hwButton variant="secondary" type="button" (click)="form.resetForm()">Reset</button>
+    </form>
+  `,
+})
+export class Example {
+  name = ''; city = '';
+  cities = [{value: 'riyadh', label: 'الرياض · Riyadh'}];
+  save() { /* application action */ }
+}
+```
+
+Load `@hawiyah/styles/styles.css` once in the host application. The optional
+`@hawiyah/styles/reset.css` is separate. Themes apply to a containing element:
+
+```html
+<main data-hw-theme="dga" data-hw-mode="light"
+      data-hw-density="comfortable" dir="rtl" lang="ar">
+  <!-- application -->
+</main>
+```
+
+Theme, locale and text direction are independent. Use `dga` for the Platforms Code
+palette or `custom` with your own documented CSS token overrides. Supply Arabic
+labels, messages, tooltips, navigation labels, and result announcements explicitly.
+
+## Inputs and outputs
+
+All value controls implement `ControlValueAccessor` for `ngModel` and
+reactive forms. Alternatively, use `[(value)]`. Do not bind both on the same
+control. Common inputs: `controlId`, `label`, `name`, `hint`, `error`, `required`,
+`disabled`, `value`; output: `valueChange`. Errors and hints connect to the native
+control through `aria-describedby`, and errors set `aria-invalid`. Use an
+application-owned `controlId` when rendering on the server or depending on an ID.
+`error` presents validation feedback; validation decisions belong to the form.
+Use Angular's `resetForm()` / `FormGroup.reset()` to reset custom control values.
+
+| Catalog entry / standalone export | Selector and specific API |
+| --- | --- |
+| Button — `HwButtonDirective` | `button[hwButton]`, `a[hwButton]`; `variant: primary/secondary/ghost/danger`, `size: sm/md/lg`. Native attributes/events/form semantics are preserved. Set button `type` explicitly; anchors require `href` and do not support disabled semantics. |
+| Field — `HwFieldComponent` | `hw-field`; required `controlId`, `label`; optional `hint`, `error`. Project a native control with that ID and explicitly connect description IDs. |
+| TextField — `HwTextFieldComponent` | `hw-text-field`; string value, `type`, `placeholder`, `autocomplete`, `inputmode`, `readOnly`; `size: sm/md/lg` (default md), `visualVariant: outline/filled` (default outline) style the native input. The native number input still emits a string; parse at your domain boundary. |
+| Textarea — `HwTextareaComponent` | `hw-textarea`; string value, `rows`, `maxLength`, `placeholder`, `readOnly`; `size: sm/md/lg`, `visualVariant: outline/filled` style the native textarea. |
+| Select — `HwSelectComponent` | `hw-select`; string value, `options: readonly Option[]`, `placeholder`; `size: sm/md/lg`, `visualVariant: outline/filled` style the native select. Native single select. |
+| Checkbox — `HwCheckboxComponent` | `hw-checkbox`; boolean value, `indeterminate`. |
+| Radio — `HwRadioComponent` | `hw-radio`; a named native radio group with a fieldset/legend, string value, `options`. |
+| Switch — `HwSwitchComponent` | `hw-switch`; boolean value, native checkbox with switch role. |
+| Combobox — `HwComboboxComponent` | `hw-combobox`; string value, `options`, `placeholder`, `emptyMessage`, `validationMessage`, `resultsMessage(count)`. Editable single selection; no async or virtualization. |
+| Tabs — `HwTabsComponent`, `HwTabComponent` | `hw-tabs` contains `hw-tab`; tabs `label`, `id`, `[(value)]`, `orientation`, optional `direction`, `activationMode: automatic/manual`, `overflow: menu/scroll` (default menu), configurable `overflowLabel`. Each tab takes `value`, `label`, `disabled` and projects its panel. Compact horizontal containers disclose excess labels; vertical tabs remain visible. |
+| Dialog — `HwDialogComponent` | `hw-dialog`; `title`, `titleId`, `[(open)]`, `closeLabel`, `closeOnBackdrop`; outputs `cancelled`, `returnValue`; methods `show(trigger?)`, `close(value?)`. Project content and `[hwDialogFooter]`. |
+| Accordion — `HwAccordionComponent` | `hw-accordion`; `items: {id,title,content,open?}[]`, `exclusive`, `groupName`; `toggled: {id,open}`. Native details/summary. Project custom native details for richer content. |
+| Card — `HwCardComponent` | `hw-card`; project `[hwCardHeader]`, body, `[hwCardFooter]`. |
+| Badge — `HwBadgeComponent` | Static label; `tone="neutral\|success\|warning\|danger\|info"`, `variant="soft\|outline\|dot"`; [source and adaptations](../../docs/nic-badges.md). |
+| Alert — `HwAlertComponent` | `hw-alert`; `title`, `tone: info/success/warning/danger`, `role: status/alert/region`, `dismissible`, `closeLabel`; `dismissed` asks the parent to remove it. |
+| Table — `HwTableComponent` | `hw-table`; `caption`, `columns: {key,label,rowHeader?}[]`, `rows: Record<string,string\|number\|null\|undefined>[]`, `emptyMessage`. Values render as escaped text. |
+| Pagination — `HwPaginationComponent` | `hw-pagination`; `[(page)]`, `totalPages`, Arabic default `label`, `previousLabel`, `nextLabel`, `pageLabel(page)`, `formatPage(page)`, `siblingCount=1`, `disabled`, `hideOnSinglePage=false`. Ellipsis disclosures use `gapLabel(start,end)`, `jumpLabel`, `goLabel`; gaps above 100 pages use bounded integer entry. Parent fetches/slices data; no navigation or scrolling is imposed. |
+| Breadcrumb — `HwBreadcrumbComponent` | `hw-breadcrumb`; `items: {label,href?}[]`, `label`. Last item is current. |
+| Progress — `HwProgressComponent` | `hw-progress`; `label`, `value: number\|null`, `max`; null is indeterminate. |
+| Skeleton — `HwSkeletonComponent` | `hw-skeleton`; `width`, `height`; decorative, hidden from assistive technology. Announce surrounding loading state once. |
+| Spinner — `HwSpinnerComponent` | `hw-spinner`; localized `label`; status announcement. |
+| Avatar — `HwAvatarComponent` | Required `name`; optional `src`, `initials`, `size="40\|64\|80\|120\|sm\|md\|lg\|xl"`, `variant="circle\|square"`. Failed images fall back to initials; changing `src` retries. [Source notes](../../docs/nic-avatars.md). |
+| Divider — `HwDividerComponent` | `hw-divider`; native horizontal rule. |
+| Tooltip — `HwTooltipComponent` | `hw-tooltip`; `text`, `id`; project short noninteractive trigger content. Focusable trigger, hover/focus opening, Escape/outside closing. Do not project buttons or links into this focusable wrapper. |
+| FileUpload — `HwFileUploadComponent` | `hw-file-upload`; readonly `File[]` value, `accept`, `multiple`. Selects local files only; no upload occurs. Forms can clear, but browsers forbid programmatically populating file pickers. |
+| Stepper — `HwStepperComponent` | `hw-stepper`; `steps: {label,description?}[]`, zero-based `current`, `label`. Noninteractive progress list. |
+| EmptyState — `HwEmptyStateComponent` | `hw-empty-state`; `title`, `description`, projected actions. |
+
+## Interaction guarantees
+
+- Combobox options preserve values and display labels. Search normalization is
+  shared with core and folds Arabic diacritics/alef variants. Typing clears the
+  committed value. Arrow keys/Home/End move the active option, Enter explicitly
+  commits, and Escape/Tab/blur close without silently selecting. Unmatched query text fails native required validation; composition input and modified editing shortcuts are preserved. The input keeps
+  focus through `aria-activedescendant`. Disabled options cannot be committed.
+- Tabs share core's wrapping navigation, skip disabled tabs, and follow RTL for
+  horizontal arrows. Manual activation uses native button Enter/Space. Panels
+  stay mounted; hidden panels leave the focus order.
+- Dialog uses native `showModal()`/`close()` after view creation. Native modality,
+  focus containment and Escape behavior require a browser with dialog support.
+  Close and destruction restore the opening trigger when it remains connected.
+  No DOM globals are touched at module evaluation. A server render leaves the
+  dialog closed; the browser opens it during view initialization.
+- The library imports no global CSS. HTML text is interpolated, never trusted HTML.
+  Theme selectors and CSS logical properties come from the shared style package.
+
+## Example and limits
+
+`examples/angular` demonstrates a bilingual service discovery/application/review
+flow, conditional guidance, file selection, and locally simulated request tracking.
+It imports the built APF library and loads `@angular/compiler` intentionally for a
+small Vite JIT demonstration. This is **not** a production Angular CLI AOT app,
+server rendering proof, or hydration certification. Use the normal Angular build
+pipeline for a production application. No request or file is submitted externally.
+
+The current table API is textual, the accordion items API is textual, and the
+combobox is local and single-select. For custom cells/details, compose the shared
+CSS classes with native Angular templates rather than injecting HTML strings.
+
+## Expanded components
+
+Every component below is standalone, exported as `Hw{Name}Component`, and uses
+`hw-kebab-case` selectors. Value controls support both `[(ngModel)]`/reactive forms
+and `[(value)]` (choose one), with inherited `controlId`, `label`, `name`, `hint`,
+`error`, `required`, `disabled`, and `readOnly`. Angular form reset clears string
+and array controls, empties NumberField, restores Slider to `min`, and RangeSlider
+to `[min,max]`. Native range, radio, and checkbox controls retain browser keyboard
+behavior. Readonly controls retain submitted values where HTML permits it.
+
+| Component | Inputs, outputs and composition |
+| --- | --- |
+| InputGroup | Project `[hwPrefix]`, a labeled native/control input, and `[hwSuffix]`; `size: sm/md/lg`. Addons remain ordinary content, so label decorative icons appropriately. |
+| PasswordField | String value; `autocomplete`, `placeholder`, `showLabel`, `hideLabel`. Reveal button keeps the same input and resets to hidden with forms. |
+| SearchField | String value/CVA; `placeholder`, `autocomplete`, `autofocus`, `searchLabel`, `clearLabel`; optional `suggestions`, `maxSuggestions` (8), `resultsMessage(count)`, `showSearchButton` (true for compatibility); `searched(query)` output and public `focus()`. |
+| NumberField | `number \| null` value; `min`, `max`, `step` (number or `any`). Empty/invalid native numeric input maps to null. Native step/min/max validation remains active. |
+| Slider | Number value; `min`, `max`, `step`; native range plus value output. |
+| RangeSlider | `[lower,upper]`; `min`, `max`, `step`, `lowerLabel`, `upperLabel`, `lowerName`, `upperName`. Crossing thumbs stop at the other value; absent distinct names, `name` submits two ordered values. |
+| Rating | Numeric value, `max` (1–20), `ratingLabel(value,max)`; named native radio choices. |
+| `HwRatingDisplayComponent / hw-rating-display` | Required `label`, numeric `value=0`, `max=5` (1–20), `showValue=true`, `valueLabel(value,max)`; noninteractive fractional aggregate score with one accessible image name. |
+| PinInput | String value, `length`; one numeric input with `one-time-code` autocomplete, Arabic-Indic/Eastern Arabic digit normalization, paste support. |
+| TagInput | `string[]`; `placeholder`, `addLabel`, `removeLabel`. Enter/comma or Add commits unique trimmed tags; repeated hidden form values. |
+| MultiSelect | `string[]`; `options: Option[]`, `searchLabel`, `emptyMessage`, `selectedMessage(count)`, `validationMessage`. Searchable checkbox list; selected values remain in FormData when search hides their checkboxes. |
+| Calendar | ISO Gregorian string value; `month`, `min`, `max`, `locale`, `calendar: gregory/islamic-umalqura`, `weekStartsOn`, `direction`, `previousLabel`, `nextLabel`; `monthChange`. Grid supports RTL-aware arrows, Home/End, PageUp/Down and Shift+PageUp/Down (year). Bounds restrict selection/focus. |
+| DatePicker | ISO Gregorian value, a custom text field and modal calendar. Accepts Calendar localization and range inputs, `dialogTitle`, `openLabel`, `closeLabel`, `calendarLabel`, `gregorianLabel`, `hijriLabel` and `unsupportedMessage`. Switching emits `calendarChange` and preserves the selected ISO date. Opening returns to its month and day. |
+| FileDropzone | `File[]`; `accept`, `multiple`, `instruction`, `selectedMessage(count)`; `rejected` emits rejected files. Native picker and local drop handling; no upload/network side effect. Browser `DataTransfer` support is needed to mirror dropped files into native FormData. Forms can clear files but cannot populate a picker from a stored path. |
+| ToggleGroup | String value for single or `string[]` for `multiple`; `options`, `variant: segmented/outline`. Single uses native radios; multiple uses pressed buttons. |
+| Popover | `label`, `triggerLabel`, `id`, `disabled`, `[(open)]`; project interactive content. Disclosure region with ordinary Tab order, outside press/Escape closing. |
+| Menu | Popover inputs plus `items: {id,label,disabled?}[]`, `action(id)`. ArrowUp/Down/Home/End navigation skips disabled items; Escape/activation returns focus. |
+| Drawer | Dialog inputs/outputs/methods plus `side: start/end/bottom`; project body and `[hwDrawerFooter]`. Native modal dialog. |
+| ToastRegion | `messages: {id,title?,message,tone?,urgent?,dismissible?}[]`, `label`, `dismissLabel`, `(dismissed)="remove($event)"`. Set `variant="banner"` and optionally `position="inline"` or a corner. A dismissal listener enables the button. Defaults are Arabic. |
+| Collapsible | `label`, `[(open)]`; native details/summary and projected body. |
+| TreeView | String selection; `nodes: {id,label,disabled?,children?}[]`, `[(expandedIds)]`, `direction`. Roving focus, RTL arrows, Home/End, Enter/Space selection. Caller supplies unique IDs. |
+| Carousel | Required label/slides; `[(current)]`, `loop=false`, `slides` and optional `slideTemplate` with `{ $implicit: HwSlide, index }`, one-based `slideLabel(index,total)`. `showIndicators=true`, localized control/indicator/description/empty labels, inert inactive slides, explicit navigation and no autoplay. [Source and motion notes](../../docs/nic-carousel.md). |
+| Link | `href`, `target`, `rel`, `current`, `variant: default/subtle`; projected link text. `_blank` defaults to `noopener noreferrer`. |
+| IconButton | Required accessible `label`; `type`, `disabled`, `pressed`, `variant`, `size`; `activated(MouseEvent)`. Project a decorative icon. |
+| ButtonGroup | `label`, `orientation: horizontal/vertical`; project native buttons or IconButtons. |
+| Chip | `tone`, `variant`, `removable`, `disabled`, `removeLabel`; `removed` asks the caller to remove it. |
+| DescriptionList | `items: {term,description}[]`, `variant: stacked/horizontal`; project richer native dt/dd if needed. |
+| Stat | `label`, `value`, `description`, `tone`; projected supplemental content. |
+| Timeline | `label`, `items: {title,description?,time?,dateTime?,state?}[]`; state is complete/current/pending. |
+| Meter | `label`, `value`, `min`, `max`, `low`, `high`, `optimum`; native meter for bounded measurements. |
+| AvatarGroup | `label`, `avatars: {name,src?}[]`, `max`, `overflowLabel(count)`; named image/initials with overflow count. |
+| DataTable | `caption`, `columns: {key,label,sortable?,rowHeader?}[]`, `rows: Record<string,string\|number\|boolean\|null\|undefined>[]`, `locale`, `emptyMessage`, `sortKey`, `sortDirection`; `sortChange({key,direction})`. Stable localized sorting, native headers and aria-sort; text cells. |
+| ServiceCard | `title`, `href`, `description`, `category`, `duration`, `fee`, `actionLabel`, `variant`; project `[hwServiceIcon]` and supplemental body. |
+| ServiceDetails | `title`, `description`, `details: {term,description}[]`, `requirements: string[]`, `requirementsLabel`; projected actions/content. |
+| PortalHeader | `brand`, `homeHref`, `mainId`, `skipLabel`, `menuLabel`, `navigationLabel`, `navigationId`, `links: {label,href,current?}[]`; project `[hwBrand]` and header actions. Mobile menu is CSS-responsive; provide unique navigationId if repeated. Optional top-level `groups` contain a label and child links. See [grouped navigation](../../docs/nic-portal-navigation.md). |
+| PortalFooter | `brand`, `copyright`, `navigationLabel`, `links`; projected supporting content. |
+| Feedback | `label`, `positiveLabel`, `negativeLabel`, `thanksMessage`, `disabled`, `[(value)]` (boolean or null initially). Emits local feedback choice; caller handles storage. |
+| CookieConsent | `title`, `description`, `acceptLabel`, `rejectLabel`, `preferencesLabel`, `[(visible)]`; `consent(accepted/rejected)` and `preferences`. Application decides persistence and script gating; this UI does not imply consent has been stored. |
+| NotificationList | `label`, `items: {id,title,description?,time?,href?,unread?}[]`, `emptyMessage`, `unreadLabel`, `dismissLabel`; `dismissed(id)`. Caller owns read/dismiss state. |
+
+The national platform patterns are configurable ordinary application content. They
+provide no seals, government endorsement, identity verification or connected
+service transactions. Strings are escaped Angular interpolation throughout.
+
+## Responsive composition
+
+Container, Stack, Inline, Grid, Columns, Sidebar, Center, Spacer, AspectRatio,
+Section, AppShell and PageHeader are native layout components. Shared props:
+`gap`, `padding`, `align`, `justify`, `wrap`; spacing accepts token numbers 0–16
+or CSS lengths. `gap`/`padding` and `columns` accept `{base,sm,md,lg,xl}` objects.
+Breakpoints live in CSS (40/48/64/80rem), so server/client layout markup matches.
+
+- Container: `maxWidth`.
+- Grid/Columns: `columns`, `minItemWidth` (adaptive auto-fit).
+- Sidebar: `sidebarWidth`, `side: start/end`, `collapseAt: sm/md/lg`; project
+  `[hwSidebar]` and main content. The main pane follows in DOM reading order.
+- AspectRatio: numeric `ratio`, default 16/9. Spacer is decorative.
+- Section: optional accessible `label`.
+- AppShell accepts `mainId`, `skipLabel`, `sidebarWidth` and `side`. Project
+  `[hwShellHeader]`, `[hwShellSidebar]`, default main content and `[hwShellFooter]`.
+  The Arabic skip link focuses the main landmark, whose default ID is `main-content`.
+  Omitted regions leave the main area at full width.
+- PageHeader: `title` (h1), `description`; `[hwBreadcrumb]` and default actions.
+
+```html
+<hw-app-shell mainId="services" sidebarWidth="18rem">
+  <hw-portal-header hwShellHeader brand="بوابة الخدمات" mainId="services"
+    skipLabel="انتقل إلى المحتوى" menuLabel="القائمة" [links]="navigation" />
+  <nav hwShellSidebar aria-label="خدماتي"><!-- native links --></nav>
+  <hw-container maxWidth="80rem" [padding]="{base: 4, lg: 8}">
+    <hw-stack [gap]="6">
+      <hw-page-header title="الخدمات" description="ابحث وابدأ طلبك" />
+      <hw-grid [columns]="{base: 1, md: 2, xl: 3}" [gap]="4">
+        @for (service of services; track service.href) {
+          <hw-service-card [title]="service.title" [href]="service.href"
+            [description]="service.description" actionLabel="عرض الخدمة" />
+        }
+      </hw-grid>
+      <hw-date-picker name="date" label="التاريخ" [(ngModel)]="date"
+        [(calendar)]="calendar" locale="ar-SA" direction="rtl"
+        calendarLabel="التقويم" gregorianLabel="ميلادي" hijriLabel="هجري (أم القرى)"
+        openLabel="فتح التقويم" closeLabel="إغلاق التقويم"
+        previousLabel="الشهر السابق" nextLabel="الشهر التالي" />
+    </hw-stack>
+  </hw-container>
+  <hw-portal-footer hwShellFooter brand="بوابة الخدمات" />
+</hw-app-shell>
+```
+
+TextField additionally supports text/email/password/tel/url/search, native
+number/range/color, and date/datetime-local/month/week/time. Its value remains a
+string; date-related inputs return browser-defined ISO-like values, color returns
+an HTML color, and number/range use numeric strings. `min`, `max`, `step`,
+`minLength`, `maxLength`, and `pattern` forward native constraints where that input
+type supports them. File, checkbox/radio, and form-action inputs have their own
+purpose-built controls/native buttons. Use NumberField for `number | null` forms,
+and DatePicker for switchable Gregorian/Umm al-Qura display with ISO storage.
+
+The default Arabic locale supplies calendar navigation, picker control labels and validation messages. Set `locale="en"` for English or use individual label inputs for application-specific wording.
+
+Calendar arithmetic comes from the shared core, `@internationalized/date`, and
+the table-backed Saudi Umm al-Qura provider. Numeric Hijri dates, including
+accessible day labels, come from that table rather than browser ICU conversion.
+Umm al-Qura supports AH 1343–1500 (1924-08-01 through 2077-11-16); outside this
+interval DatePicker retains the ISO value and presents `unsupportedMessage`,
+while Gregorian entry remains available. Calendar edge navigation stays bounded. Locale and calendar do not determine
+text direction. Calendar bounds and the verified Umm al-Qura supported interval
+follow the shared core's documented contract.
+
+Maps, rich-text editors, charts, code editors, PDF viewers, CAPTCHA and payments
+remain integration boundaries. Compose their provider SDKs in Card/Section/Grid,
+provide accessible fallbacks, and keep credentials and payment/identity actions
+in the application. DataTable has no editing or virtualization; TreeView has no
+drag/drop; these APIs make no claim to supply those larger engines.
+
+## Portal shell
+
+[`HwPortalLayoutComponent` and `HwSecondaryNavComponent`](PORTAL.md) provide a
+complete Arabic-default portal shell with responsive navigation and footer.
+Run the Angular example with `?preview=portal` to use the native composed shell.
+
+## NIC card composition
+
+See [cards](../../docs/nic-cards.md) for source-mapped spacing, variants, whole-card links, disabled semantics and content classes. Native framework consumers include `?preview=nic`; vanilla uses the documented semantic HTML recipe.
+
+See [NIC button variants](../../docs/nic-buttons.md) for all ten appearances,
+interaction states, dark-surface use and density adaptations.
+
+[Ready component examples](../../docs/ready-component-examples.md) cover all five
+alert/notification tones, header/footer composition and guide-only navigation containment.
+
+InputGroup tracks value presence for projected native `.hw-input` / `.hw-select`
+controls after Angular renders; no vanilla enhancer is required. Keep labels
+and hints outside the joined row. See [NIC input composition](../../docs/nic-inputs.md).
+# Native choice read-only state
+
+`HwCheckboxComponent`, `HwRadioComponent` and `HwSwitchComponent` accept `readOnly`.
+The control remains keyboard-focusable and submits its value, while pointer and
+keyboard activation leave its value and radio peers unchanged. Disabled remains
+a separate native state. See [NIC states](../../docs/nic-choices.md).
+
+
+[Site verification](../../docs/site-verification.md) composes a native disclosure above the header with deployment-owned domain and certificate information. [Grouped portal footers](../../docs/nic-footer.md) add navigation groups, support actions, legal links and identity slots.
+
+[Link and breadcrumb states](../../docs/nic-links.md) document neutral/standalone variants, disabled destinations, source contrast substitutions and native adapter APIs.
+
+
+### Table presentation and empty results
+
+`Table` and `DataTable` expose `variant="default|striped|bordered"`,
+`size="sm|md|lg"` and `emptyMessage`. DGA cells have a 48px default minimum;
+40px/56px alternate sizes and striped/bordered variants are Hawiyah extensions.
+Captions name keyboard-focusable horizontal scroll containers; row-header
+columns render native `th scope="row"`. Empty data spans the column count and
+uses an Arabic message by default. Sorting does not mutate caller records.
+The default sort locale is `ar-SA`. Both component hosts shrink inside grid/flex
+layouts so overflow stays inside the table wrapper.
+See [table evidence and adaptations](../../docs/nic-tables.md).
+
+Rating inputs select whole numbers; finite prefilled values are clamped to the normalized maximum and floored. Fractional averages belong in `RatingDisplay`. Nonfinite maxima fall back to 5 and nonfinite values to 0. Arabic labels and Latin digits are the defaults.
+
+
+### Search suggestions
+
+SearchField accepts local string suggestions and remains a free-text input.
+With suggestions supplied it exposes an editable combobox/listbox, highlighted
+matches and a polite result count. Arrow keys wrap through matches; Enter on an
+active suggestion selects it and prevents form submission. Ordinary Enter with
+no active suggestion emits `searched` with a trimmed, nonempty query and keeps
+native form submission available. Choose either the search callback or the
+form's submit handler for the application request; wiring both duplicates it.
+The optional icon search action is a non-submit button and uses the callback.
+Arabic clear/search labels are defaults and can be localized.
+
+Escape dismisses an open list before reaching an enclosing dialog; another
+Escape can dismiss the dialog. Composition/modifier keys do not commit matches.
+Readonly inputs remain searchable but cannot edit/clear/select suggestions;
+disabled inputs cannot search. Blur, outside press, reset and changed suggestion
+configuration clear active-option state. No remote search service is called.
+
+### Content navigation
+
+`HwContentNavigationComponent` (`hw-content-navigation`) follows application-owned section IDs using nested
+`items: {id, label, disabled?, children?}[]`. Options are `label` (Arabic default),
+`showHeading` (true), `sticky` (false), `scrollRoot` (null/window) and `offset`
+(80px). `(currentChange)="onCurrentChange($event)"` reports the current section ID. Ordinary
+activation scrolls without changing the URL; keyboard activation also focuses
+the target. Modified anchor clicks retain browser behavior. Disabled entries
+remain noninteractive text links; no section content is created or hidden.
+
+```html
+<!-- Add HwContentNavigationComponent to the host component's imports. -->
+<hw-content-navigation [items]="[{id: 'requirements', label: 'المتطلبات'}]" />
+<section id="requirements"><h2>المتطلبات</h2></section>
+```