@hawiyah/angular 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/NOTICE

@@ -0,0 +1,19 @@
+Hawiyah — هوية
+
+تم التطوير بواسطة فريق التطوير في قطاع المنصات الوطنية - مركز المعلومات الوطني
+Developed by the Development Team in the National Platforms Sector — National Information Center.
+
+Copyright 2026 Mohamed Embarak
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+This distribution includes an Umm al-Qura calendar table derived from
+HijriDate 2.3.0, Copyright (c) 2018 Mohammed Alshehri, licensed under MIT.
+The full notice and provenance are in packages/core/third-party in the
+source repository and third-party in the core package.
+
+Brand source fonts are licensed separately under the SIL Open Font License
+1.1. The unmodified notices accompany their files in brand/third-party.
+Font software and third-party dependencies retain their own licenses.
+The Hawiyah name and identity do not imply endorsement by Saudi Arabia's
+Digital Government Authority. Apache 2.0 does not grant trademark rights.

package/PORTAL.md

@@ -0,0 +1,72 @@
+# Portal layout
+
+Import the standalone `HwPortalLayoutComponent` to get the header, optional
+secondary navigation, breadcrumb, focusable main container and footer together.
+
+```html
+<hw-portal-layout brand="هوية" [links]="links" [secondaryNavigation]="links"
+  [breadcrumbs]="breadcrumbs" [footerLinks]="footerLinks">
+  <h1>الخدمات</h1>
+</hw-portal-layout>
+```
+
+```ts
+links = [{ label: 'الخدمات', href: '/services', current: true }];
+breadcrumbs = [{ label: 'الرئيسية', href: '/' }, { label: 'الخدمات' }];
+footerLinks = [{ label: 'الخصوصية', href: '/privacy' }];
+```
+
+Inputs: `brand` (required), `homeHref`, `links`, `secondaryNavigation`, `footerLinks`,
+`breadcrumbs`, `copyright`, `mainId`, `lang` (ar), `dir` (rtl). Labels default to
+Arabic: `skipLabel`, `menuLabel`, `navigationLabel`, `secondaryLabel`,
+`breadcrumbLabel`, `footerLabel`. Set `lang="en" dir="ltr"` and translate labels
+and content for English. Language and direction remain independent. Use explicit
+stable `mainId`/standalone `navigationId` when serializing independent app roots.
+
+Content projection: `[hwBrand]` for actual brand artwork, `[hwPortalActions]`
+for header actions, `[hwPortalFooter]` for additional footer content, default for
+main page content. `HwSecondaryNavComponent` is independently available with
+`items` and `label`. It uses ordinary links with `aria-current`, not tab/menu roles.
+
+Standalone `HwPortalHeaderComponent` retains its inputs. Escape closes the mobile
+disclosure and focuses its toggle; link selection, outside press and focus
+leaving close it. Tab remains native and desktop links stay visible. Each header
+gets a distinct navigation ID unless supplied explicitly. No vanilla controller
+is attached to Angular-owned DOM.
+
+The 48rem mobile breakpoint is a Hawiyah adaptation. Shared tokens support DGA,
+Hawiyah and custom themes. No animation is added by this layout. Source-informed
+composition does not establish exact visual parity or DGA certification.
+
+## Mobile navigation bar
+
+Use `variant="mobile"` on `SecondaryNav` (React/Vue) or `hw-secondary-nav`
+(Angular). Items accept an optional decorative `icon` name from the bundled icon
+stylesheet, such as `home-01`, `search-01` or `menu-01`; labels remain required.
+Vanilla uses `data-variant="mobile"` and the same semantic HTML:
+
+```html
+<nav class="hw-secondary-nav" data-variant="mobile" aria-label="تنقل الجوال">
+  <ul>
+    <li><a href="/" aria-current="page"><span class="hw-icon" data-icon="home-01" aria-hidden="true"></span><span>الرئيسية</span></a></li>
+    <li><a href="/services"><span class="hw-icon" data-icon="search-01" aria-hidden="true"></span><span>الخدمات</span></a></li>
+  </ul>
+</nav>
+```
+
+The bar uses equal-width items, 24 px icons, a 70 px minimum height, wrapped labels
+and a top current-page indicator. It is in normal flow and does not cover page
+content. Safe-area bottom padding accommodates mobile devices; the source OS
+home indicator is not reproduced. The application owns route/current updates.
+These are page links, not content tabs: preserve native Tab/Enter navigation.
+
+DGA/custom color transitions use `--hw-duration-tab-bar: 300ms` and
+`--hw-ease-tab-bar: cubic-bezier(0, 0, 0.58, 1)`. Hawiyah remains immediate by
+default. Reduced motion removes transitions; forced colors retains the selected
+top border and keyboard focus. Hover does not mark a route selected.
+
+Source Mobile `8332:24202` → `8332:24242` → `8332:24282` supports color changes,
+not a sliding indicator or tab-panel animation. Semantic colors adapt to theme;
+icon color follows the label, since imported icon override endpoints were not
+resolved. Arabic width differs from English in the source, so no fixed item
+width is imposed. This is a source-informed composition, not certified parity.

package/README.md

@@ -1,3 +1,335 @@
-# Temporary Holding Version
+# @hawiyah/angular
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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>
+```

package/dist/LICENSE

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.