@hawiyah/react 0.0.0-stage → 0.2.1

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,74 @@
+# Portal layout
+
+`PortalLayout` composes `PortalHeader`, optional `SecondaryNav`, `Breadcrumb`,
+a focusable main container and `PortalFooter`. It defaults to Arabic and RTL.
+It is a public portal shell; keep application routing and page content in the app.
+
+```tsx
+import { PortalLayout } from '@hawiyah/react';
+import '@hawiyah/styles/styles.css';
+
+<PortalLayout brand="هوية"
+  headerProps={{ brandHref: '/', navigation: [{ label: 'الخدمات', href: '/services', current: true }] }}
+  secondaryNavigation={[{ label: 'دليل الخدمات', href: '/services', current: true }]}
+  breadcrumbs={[{ label: 'الرئيسية', href: '/' }, { label: 'الخدمات', current: true }]}
+  footerProps={{ links: [{ label: 'الخصوصية', href: '/privacy' }] }}>
+  <h1>الخدمات</h1>
+</PortalLayout>
+```
+
+`headerProps` accepts the existing header API plus `menuLabel`, `navigationId`,
+and `navigationLabel`. `actions`/`notice` remain composable React nodes. Supply
+your actual brand SVG as `brand`; no government artwork is inferred. `footerProps`
+accepts the existing footer's brand, description, links, linksLabel and legal.
+`mainId` is generated with React `useId` unless supplied. `skipLabel`,
+`breadcrumbLabel` and `secondaryLabel` override the Arabic accessible labels.
+
+For English, set `lang="en" dir="ltr"` and translate the content and labels,
+including `skipLabel`, `breadcrumbLabel`, `secondaryLabel`,
+`headerProps.navigationLabel`, `headerProps.menuLabel`, `footerProps.linksLabel`.
+Language and direction are independent props.
+
+Standalone `PortalHeader` adds a mobile disclosure when `navigation` has items;
+set `mainId` to render its skip link. Escape closes and focuses the toggle;
+selection, outside press and focus leaving close it. Tab is not trapped. The
+links stay visible at desktop widths. Multiple headers receive separate IDs.
+`SecondaryNav` takes `items` and `label`; these are ordinary page links with
+`aria-current`, not tabs or menus.
+
+The 48rem disclosure breakpoint is an intentional Hawiyah policy. The layout uses
+shared tokens in DGA, Hawiyah and custom themes, and introduces no animation.
+Source-informed composition does not claim pixel 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,462 @@
-# Temporary Holding Version
+# @hawiyah/react
 
-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.
+Native React 19 components for Hawiyah — هوية, a UI library built to comply with
+the DGA Platforms Code. React owns
+all rendered elements. No vanilla controller is mounted into a React tree.
+
+```tsx
+import { useState } from 'react';
+import '@hawiyah/styles/styles.css';
+// Optional, only when the application wants the reset:
+import '@hawiyah/styles/reset.css';
+import { Button, Combobox, Dialog, TextField } from '@hawiyah/react';
+
+function Application() {
+  const [city, setCity] = useState('');
+  return (
+    <form>
+      <TextField label="الاسم الكامل" name="name" autoComplete="name" required />
+      <Combobox
+        label="المدينة"
+        name="city"
+        options={[{ value: 'riyadh', label: 'الرياض' }]}
+        value={city}
+        onValueChange={setCity}
+        required
+      />
+      <Button type="submit">متابعة</Button>
+    </form>
+  );
+}
+```
+
+Install with `npm install @hawiyah/styles @hawiyah/react`. This is a pre-1.0
+release, so a minor version may still change its API. React and React DOM are
+peers; `@hawiyah/core` provides the shared, pure keyboard and combobox behavior.
+Styles are never imported implicitly. When consuming this repository's workspace
+instead of npm, build the packages before importing their exports. Importing and server-rendering this package require no browser globals.
+Stable associations use React `useId`, including during hydration.
+
+## Common conventions
+
+Native attributes, events, `className`, ARIA attributes and React 19 `ref` props
+are passed to the component's principal native element. `TextField`, `Textarea`,
+`Select`, `Checkbox`, `Radio`, `Switch`, `Combobox` and `FileUpload` forward refs
+to their actual inputs, not their label wrappers. Use normal React
+`value`/`defaultValue` or `checked`/`defaultChecked` and `onChange` for native
+controls. `Button` defaults to `type="button"`; explicitly opt into form submit.
+
+Labels, hints and errors are renderable React content. Hints/errors are associated
+with the control and errors set `aria-invalid`. Required native controls retain
+browser constraint validation. `Field` provides label/description context for one
+control; use the same `controlId` and input `id` if choosing your own identifier.
+Use native `fieldset` and `legend` for related checkbox/radio groups.
+
+Set `dir` and `lang` independently at the document or subtree. Horizontal Tabs
+follow computed direction; vertical arrows stay vertical. Theme, mode and density
+are CSS attributes on an ancestor:
+
+```html
+<div dir="rtl" lang="ar" data-hw-theme="dga"
+     data-hw-mode="dark" data-hw-density="comfortable">…</div>
+```
+
+Default auxiliary labels are English; provide Arabic or another language through
+label/message props. Business dates and numbers can use `@hawiyah/core` formatters
+with explicit locale, calendar and time zone. No component infers locale from RTL.
+
+## Catalog
+
+| Component | Composition and important props |
+| --- | --- |
+| `Button` | Native button; `variant="primary\|secondary\|ghost\|danger"`, `size="sm\|md\|lg"`, `loading` disables and sets busy. |
+| `Field` | `label`, `hint`, `error`, `required`, `controlId`; wrap one form control as children. |
+| `TextField` | Native input attributes plus `label`, `hint`, `error`; supports text/email/date/number/etc. |
+| `Textarea` | Native textarea plus label/hint/error. |
+| `Select` | Native select plus label/hint/error; `options: Option[]` or native option/optgroup children. Native `multiple` is supported. |
+| `Checkbox` | Native checkbox plus label/hint/error and `indeterminate`. |
+| `Radio` | Native radio plus label/hint/error; supply a shared `name` for a native group. |
+| `Switch` | Native checkbox with `role="switch"`, label/hint/error. |
+| `Tabs` | `items: {value,label,content,disabled?}[]`, required `label`, `value`/`defaultValue`, `onValueChange`, `orientation`, `activationMode`, `overflow: menu/scroll` (default menu), configurable `overflowLabel`. Horizontal compact containers move excess labels into a keyboard-accessible disclosure; vertical tabs remain visible. |
+| `Dialog` | Required `title`; `description`, `trigger`, `open`/`defaultOpen`, `onOpenChange`, `closeLabel`, `closeOnBackdrop`; children/footer can render from `{close}`. |
+| `Combobox` | Single selection from `Option[]`; label/hint/error, `value`/`defaultValue`, `onValueChange(value, option?)`, `onInputChange(query)`, `open`/`defaultOpen`, `onOpenChange`, native form attributes. |
+| `Accordion` | `items: {value,title,content,open?,defaultOpen?,onOpenChange?}[]`; `exclusive` uses a native details name group. |
+| `Card` | Native article; header/footer slots and body children. |
+| `Badge` | Static label; `tone="neutral\|success\|warning\|danger\|info"`, `variant="soft\|outline\|dot"`; [source and adaptations](../../docs/nic-badges.md). |
+| `Alert` | `tone="info\|success\|warning\|danger"`, optional text `title`, children. Default role is status (danger: alert); override role for static content. |
+| `Table<Row>` | `caption`, `columns: {key,header,cell(row,index),rowHeader?}[]`, `rows`, `rowKey`, `wrapperProps`; alternatively native table children. |
+| `Pagination` | `totalPages`, `page`/`defaultPage`, `onPageChange`; Arabic default `label`, `previousLabel`, `nextLabel`, `getPageLabel`, `formatPage`; `siblingCount` (default 1), `disabled`, `hideOnSinglePage` (default false). Ellipsis disclosures use `getGapLabel(start,end)`, `jumpLabel`, `goLabel`; gaps above 100 pages use bounded integer entry. Parent fetches/slices data; no navigation or scrolling is imposed. |
+| `Breadcrumb` | `items: {label,href?,current?}[]`, localized `label`; last item is current. |
+| `Progress` | Native progress with required accessible `label`, `value`, `max` (100); omit value for indeterminate. |
+| `Skeleton` | Decorative span, hidden from assistive technology; set dimensions via className/style. |
+| `Spinner` | Status span; localized `label` (default “Loading”). |
+| `Avatar` | 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` | Native horizontal rule. |
+| `Tooltip` | Plain string `content`; one focusable React element as children. |
+| `FileUpload` | Native file input with label/hint/error; `accept`, `multiple`, native `onChange`, `onFilesChange(File[])`, optional supplementary children. |
+| `Stepper` | `items: {value,label,description?,status?}[]`, `current`, accessible `label`. Status: complete/current/upcoming. Static progress, not navigation. |
+| `EmptyState` | Required `title`; optional `description`, decorative `icon`, `action`, children. |
+
+All prop interfaces, `TabItem`, `AccordionItem`, `TableColumn<Row>`,
+`BreadcrumbItem`, `StepItem`, and core `Option`, `Direction`, `Orientation` types
+are exported. Option values and item values must be unique stable strings.
+
+## Stateful controls
+
+### Tabs
+
+```tsx
+<Tabs
+  label="Application sections"
+  value={section}
+  onValueChange={setSection}
+  activationMode="manual"
+  items={[
+    { value: 'details', label: 'Details', content: <Details /> },
+    { value: 'history', label: 'History', content: <History /> },
+  ]}
+/>
+```
+
+Arrows wrap and skip disabled items; Home/End move to the first/last enabled tab.
+Automatic activation (default) selects while moving focus. Manual activation
+selects through the native button's Enter/Space/click behavior. Inactive panels
+stay mounted with `hidden`, preserving their form state. The first enabled tab
+is the default and the fallback if the supplied selection is unavailable.
+
+### Dialog
+
+```tsx
+<Dialog title="Review request" trigger={<Button>Review</Button>}
+  footer={({ close }) => <Button onClick={close}>Done</Button>}>
+  {({ close }) => <p>Review your details before continuing.</p>}
+</Dialog>
+```
+
+The wrapper invokes native `showModal()` and `close()`; it requires native modal
+dialog support. Native modality contains focus and makes the background inert.
+Escape requests closing; set `onCancel={event => event.preventDefault()}` to
+cancel that action. Backdrop closing defaults on and can be disabled.
+`autoFocus` on a child selects initial focus. Closing restores the prior focused
+element when it remains connected. The optional trigger is one button-like React
+element that forwards `onClick`; its original handler runs first and can prevent
+opening. You can also use a separate button with controlled `open`.
+
+Server rendering emits a closed dialog; a default-open dialog becomes modal after
+hydration. For controlled state, handle `onOpenChange` to apply requests from the
+close button, Escape or native dialog forms.
+
+### Combobox
+
+The editable single-select input shares `transitionCombobox` and
+`getComboboxOptions` with other adapters. Arabic diacritics/alef variants and
+letter case are folded for searching, without changing labels or stored values.
+Opening a committed selection displays all options. Typing clears the committed
+selection; arrows/Home/End change the active option, and Enter or pointer click
+commits an enabled option. Focus stays in the input. Escape/Tab close the list;
+blur keeps the query without silently selecting.
+
+`name` belongs to a hidden native input containing the selected option value.
+Arbitrary text does not become a submitted value. `required` uses custom validity
+to require a committed choice; localize its message with `requiredMessage`.
+`disabled`, `readOnly`, `form`, forwarded input refs, and native form resets are
+supported. A reset restores an uncontrolled `defaultValue`; controlled state
+continues to belong to the caller. When controlled, apply `onValueChange`, including
+its empty string when the user edits the selection.
+
+Use `getResultsMessage(count)` for the live region and `emptyMessage` for the
+empty list. There is no multiselect, remote fetching, option virtualization, or
+custom option rendering in this version. The caller can supply updated options.
+
+### Tooltip and file upload
+
+Tooltip adds a description to its focusable child, opens on hover/focus, and closes
+on Escape or when focus/pointer leave. Custom child components must forward
+`aria-describedby`. Keep tooltip text noninteractive; essential instructions belong
+in visible labels/hints. FileUpload is a native file picker. It does not upload,
+validate file contents, or create network requests.
+
+## Example and checks
+
+`examples/react` is a complete local service application: conditional applicant
+fields, Arabic city search, review dialog, request history/filter/pagination,
+independent locale/direction/mode toggles and a service guide. Its sample requests
+are ephemeral in-memory data. Build the workspace packages, then run Vite using
+`examples/react/vite.config.ts` on port 4174.
+
+Focused tests cover import/server rendering without DOM globals, field/ref/form
+associations, RTL/manual/controlled tabs, Arabic combobox search and commits,
+controlled typing, reset, modal lifecycle calls, tooltip dismissal and bounded
+pagination. JSDOM dialog methods are test doubles; native modality and browser
+focus containment need the browser integration suite.
+
+## Expanded catalog: 50 additional components
+
+The package now exports 77 components. Added components use the same native
+attributes/ref conventions and shared styles. Array values and item identifiers
+must be unique. Custom form controls support `value`/`defaultValue` and
+`onValueChange`; uncontrolled values return to their defaults on native form reset,
+including forms associated through `form`. Canceled reset events are respected.
+Controlled values remain owned by the application.
+
+| Added control | API and behavior |
+| --- | --- |
+| `InputGroup` | `start`/`end` adornments and control children; surrounding `Field` supplies the accessible label. |
+| `PasswordField` | TextField props plus `visible`/`defaultVisible`, `onVisibleChange`, `showLabel`, `hideLabel`. Reveal preserves the native input and its value. |
+| `SearchField` | String `value/defaultValue`, `onValueChange`, native `onChange`, `clearLabel`; optional `suggestions`, `maxSuggestions` (8), `resultsMessage(count)`, `onSearch(query)`, `showSearchButton` (false), `searchLabel`. Native input props/ref and field decoration are preserved. |
+| `NumberField` | Native number input with label/hint/error, min/max/step and normal React input events. Empty remains empty; it is not coerced to zero. |
+| `Slider` | Numeric value/defaultValue, `onValueChange`, min/max/step, `showValue`, `formatValue`; one labelled native range. |
+| `RangeSlider` | Numeric `[lower,upper]`, `onValueChange`, min/max/step; required `lowerLabel`/`upperLabel`, optional group `label`. `lowerName`/`upperName` or repeated `name` submit both values. Native handles cannot cross. |
+| `Rating` | Numeric value/defaultValue, `onValueChange`, max (1–20, default 5), label/name/required, `getRatingLabel`; one native radio group. |
+| `RatingDisplay` | Required `label`, numeric `value=0`, `max=5` (1–20), `showValue=true`, `getValueLabel(value,max)`; noninteractive fractional aggregate score with one accessible image name. |
+| `PinInput` | String value/defaultValue, `onValueChange`, `length` (default 6), optional decorative `showSlots`; one accessible OTP input normalizes Arabic-Indic and Eastern Arabic digits, including pasted input. |
+| `TagInput` | String array value/defaultValue, `onValueChange`, name, required, `getRemoveLabel`, `requiredMessage`; Enter/comma commits a unique tag, empty Backspace removes the last tag. Each committed tag produces a native form value. |
+| `MultiSelect` | Required label and options; string array value/defaultValue, `onValueChange`, name, required, `searchLabel`, `emptyMessage`, `requiredMessage`. Searchable native checkboxes; filtered-out selections retain repeated form values. |
+| `Calendar` | ISO Gregorian value/defaultValue, `onValueChange`; month/defaultMonth, `onMonthChange`; locale/calendar/weekStartsOn, min/max, `isDateDisabled`, disabled/readOnly, optional form/name and localized toolbar/day labels. |
+| `DatePicker` | Typed ISO text input plus Calendar in a native modal. Adds calendar/defaultCalendar, `onCalendarChange`, localized calendar selector labels, calendar button/dialog labels and unsupported-range message. |
+| `FileDropzone` | Native file input props plus `onFilesChange(File[])`, `dropLabel`, `getRejectedMessage`; accepted dropped files populate the actual native input. The picker and dropped selection participate in forms. No upload occurs automatically. |
+
+Native `TextField` input types retain their platform semantics: text/search/tel/url
+are strings; email uses native validation; number uses native numeric constraints
+and permits empty input; date/month/week/time/datetime-local use HTML's date/time
+value formats; color uses the native picker. Use `FileUpload`/`FileDropzone` for
+file values, Checkbox/Radio/Switch for checked state, and Slider/RangeSlider for
+range controls. A native date input stores Gregorian ISO dates regardless of the
+calendar used to select or describe a date.
+
+### Saudi date selection
+
+```tsx
+const [date, setDate] = useState('2026-10-28');
+const [calendar, setCalendar] = useState<'gregory' | 'islamic-umalqura'>('islamic-umalqura');
+
+<DatePicker
+  label="تاريخ الموعد"
+  name="appointment"
+  value={date}
+  onValueChange={setDate}
+  calendar={calendar}
+  onCalendarChange={setCalendar}
+  locale="ar-SA"
+  calendarSystemLabel="التقويم"
+  gregorianLabel="ميلادي"
+  hijriLabel="هجري — أم القرى"
+  calendarLabel="اختر تاريخ الموعد"
+  buttonLabel="فتح التقويم"
+  previousLabel="الشهر السابق"
+  nextLabel="الشهر التالي"
+  closeLabel="إغلاق"
+  required
+/>
+```
+
+The picker includes a Gregorian/Umm al-Qura selector. Switching display systems
+preserves the exact ISO day, and reopening returns to the selected date's month.
+Calendar names, navigation, picker controls and validation messages default to Arabic. Set `locale="en"` for English copy or pass a label prop to override a particular control.
+
+Direction and locale remain independent of calendar. Calendar's arrows follow
+visual RTL/LTR direction; Up/Down move a week, Home/End move within the week,
+PageUp/PageDown move a month, and Shift+PageUp/PageDown move a year. Disabled days
+are skipped and focus remains on one roving date button.
+
+Umm al-Qura arithmetic and numeric date labels use the shared Saudi reference
+table through `@hawiyah/core`, including `formatCalendarDate`; they do not rely on
+ICU's differing historical/future numeric Hijri fields. The supported table spans
+**1924-08-01 through 2077-11-16 (AH 1343–1500)**. Navigation stops at these
+boundaries. When a Gregorian selected date lies outside this range, switching to
+Hijri preserves the ISO input, shows a localized unsupported-range message, and
+renders no fabricated Hijri selection, and blocks native form submission with custom validity and `aria-invalid`. Switching back to Gregorian clears the calendar-range error while keeping application min/max constraints. Use `unsupportedCalendarMessage` to
+translate that explanation. Read the workspace calendar evidence for provenance
+and verification; this interface is not an official service or certification.
+
+`getDayLabel` customizes Calendar date announcements. Supply stable initial
+`month`/`defaultMonth` or `value` when a server-rendered view must be independent of
+the current date. Standalone Calendar submits its selected supported date through
+an optional hidden `name`; use DatePicker when native required/date validation is
+needed. `isDateDisabled` applies to both the calendar and the DatePicker's native
+input validation. `unavailableMessage` localizes custom date validation.
+
+| Added interaction | API and behavior |
+| --- | --- |
+| `ToggleGroup` | Required label/options, `variant="segmented\|outline"`. Default single selection uses native radios with string value; `multiple` uses pressed buttons with string-array value and repeated hidden form values. Both support defaultValue/onValueChange/name/form/disabled/readOnly. |
+| `Popover` | Required title/trigger, open/defaultOpen/onOpenChange and region children. Trigger toggles a labelled disclosure; outside press and Escape close. Interactive content uses ordinary Tab. |
+| `Menu` | Required trigger/label and `items: {value,label,disabled?,href?,onSelect?}[]`; open/defaultOpen/onOpenChange and `onAction(value)`. Up/Down/Home/End skip disabled entries; Escape/action return focus. |
+| `Drawer` | Dialog props plus `side="start\|end\|bottom"`; same native modal and focus behavior as Dialog. |
+| `ToastRegion` | `messages: {id,title?,description,tone?,urgent?,dismissible?}[]`, `onDismiss(id)`, `label`, `getDismissLabel(message)`. Choose `variant="banner"` and optionally `position="inline"` or a corner. Buttons require an `onDismiss` handler. Arabic labels default to الإشعارات and إغلاق الإشعار with available message text. |
+| `Collapsible` | Native details with title, open/defaultOpen/onOpenChange, disabled and children. |
+| `TreeView` | Required label and `items: {id,label,disabled?,children?}[]`; value/defaultValue/onValueChange and expanded/defaultExpanded/onExpandedChange. Visible nodes have tree levels, positions and roving focus; horizontal expansion follows RTL. |
+| `Carousel` | Required label/slides; `index/defaultIndex/onIndexChange`, `loop=false`, renderable `slides`, zero-based `getSlideLabel(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). |
+
+```tsx
+// Toast state is ordinary application state. There is no global singleton.
+const [messages, setMessages] = useState([
+  { id: 'saved', description: 'تم حفظ المسودة', tone: 'success' as const },
+]);
+<ToastRegion label="الإشعارات" messages={messages}
+  getDismissLabel={() => 'إغلاق الإشعار'}
+  onDismiss={id => setMessages(current => current.filter(item => item.id !== id))} />
+```
+
+Popover/Menu trigger elements must forward native button event and ARIA props.
+TreeView is a single-selection navigation structure, without drag/drop or virtual
+rows. Caller-owned items and toast messages remain unchanged until the caller
+applies a callback.
+
+| Added content/pattern | API and behavior |
+| --- | --- |
+| `Link` | Native anchor with optional `external` (new tab and noopener/noreferrer). |
+| `IconButton` | Button props plus required accessible `label`; icon children are decorative. |
+| `ButtonGroup` | Native group with required accessible `label` and button children. |
+| `Chip` | Text children, optional tone/onRemove/removeLabel/disabled. |
+| `DescriptionList` | `items: {term,description,key?}[]`; native dl/dt/dd. |
+| `Stat` | Required label/value; optional description/trend content. Values are formatted by the caller. |
+| `Timeline` | `items: {id,title,description?,dateTime?,dateLabel?,status?}[]`; status complete/active/upcoming and optional label. |
+| `Meter` | Native meter attributes with required accessible label. |
+| `AvatarGroup` | Required items/label, max (default 5), getOverflowLabel. Items use AvatarProps. |
+| `DataTable<Row>` | Required caption/rows/columns; columns have key/label/sortable/render/rowHeader. Optional rowKey, sort/defaultSort/onSortChange, locale, emptyMessage, getSortLabel. Stable immutable localized sorting and native aria-sort headers. |
+| `ServiceCard` | Required title; description/category/icon/metadata, href/actionLabel or action slot, body children. |
+| `ServiceDetails` | Required title; description/metadata/requirements/requirementsLabel/action and children. |
+| `PortalHeader` | Required brand slot, optional brandHref/navigation/navigationLabel/actions/notice and children. Navigation items are label/href/current. Optional top-level `groups` contain a label and child links. See [grouped navigation](../../docs/nic-portal-navigation.md). |
+| `PortalFooter` | Optional brand/description/links/linksLabel/legal and children. |
+| `Feedback` | Required question label; value/defaultValue/onValueChange for `{helpful:'yes'\|'no'\|'',comment}` and `onFeedback` on native submit; translated yes/no/comment/submit/success labels. |
+| `CookieConsent` | Required title/description; value/defaultValue/onValueChange (`accepted`/`rejected`/null), translated buttons and optional policy link. Null displays the notice. Persistence and cookie activation belong to the application. |
+| `NotificationList` | Required label/items; items id/title/description/href/dateTime/dateLabel/read. Optional emptyMessage, onMarkRead, getMarkReadLabel, unreadLabel. |
+
+Platform patterns are configurable ordinary content. Supply your own brand,
+service facts, legal text and links. They do not provide government seals, verified
+trust status, identity verification, authentication, submissions or storage.
+Feedback callbacks report local user choices; applications own asynchronous
+submission outcomes. DataTable provides native sorting, without editing,
+virtualization, selection or a remote data engine; existing Table remains fully
+composable for those integrations.
+
+### Layout primitives
+
+| Primitive | Native composition |
+| --- | --- |
+| `Container` | Div with optional maxWidth. |
+| `Stack` | Vertical flex div. |
+| `Inline` | Horizontal flex div with optional wrap. |
+| `Grid` | Div with responsive columns or minItemWidth. |
+| `Columns` | Div with responsive explicit columns. |
+| `Sidebar` | Two child areas; side/sidebarWidth/collapseAt control responsive placement. |
+| `Center` | Centered content div. |
+| `Spacer` | Flexible space div. |
+| `AspectRatio` | Div with positive numeric ratio. |
+| `Section` | Semantic section with common layout props. |
+| `AppShell` | Supply `header`, `sidebar` and `footer` content around the main landmark. The Arabic skip link focuses main. Set `mainId` to choose its target ID and `skipLabel` to localize the link. |
+| `PageHeader` | Native header with title h1, description/breadcrumb/actions and children. |
+
+The first ten primitives accept shared `LayoutProps` and native attributes/refs.
+`gap` and `padding` accept token numbers 0–16 or CSS lengths, including responsive
+objects `{base,sm,md,lg,xl}`. `columns` accepts positive integer values or the same
+responsive object. Common props also include align, justify and wrap. Styles come
+from `layoutStyles` CSS variables; there are no JS viewport measurements. Consumer
+`style` overrides can explicitly replace generated properties.
+
+```tsx
+<Container maxWidth="76rem" padding={{ base: 4, lg: 8 }}>
+  <Stack gap={6}>
+    <PageHeader title="الخدمات" description="اختر الخدمة المناسبة" />
+    <Sidebar side="start" sidebarWidth="18rem" collapseAt="md" gap={6}>
+      <aside>مرشحات الخدمات</aside>
+      <Grid columns={{ base: 1, md: 2, xl: 3 }} gap={4}>
+        <ServiceCard title="تصريح نشاط" href="/services/permit" actionLabel="تفاصيل الخدمة" />
+      </Grid>
+    </Sidebar>
+  </Stack>
+</Container>
+```
+
+### Integration boundaries and evidence
+
+Maps, rich-text editors, charts, code editors, PDF viewers, CAPTCHA and payment
+engines belong to their specialist libraries/services. Mount the real engine in
+an ordinary React-owned region or Card/AspectRatio with its own accessible name,
+loading/error UI and lifecycle cleanup. Use Field hint/error associations around
+real input engines and Dialog only when an engine's focus model supports native
+modality. Pass theme tokens/direction through the engine's documented API, use
+its documented ref/event integration, and adapt actual resulting values into your
+form state. These components do not simulate an engine, credential exchange or
+payment outcome, and do not inject unsafe HTML.
+
+Expansion regressions cover all 50 additions under DOM-free server rendering,
+responsive CSS-variable output, PIN digit normalization, repeated values and
+external/canceled resets, ordered range handles, Saudi calendar navigation and
+range boundaries, picker system switching/reopening/unsupported dates, menu and
+tree focus, popover dismissal, table sorting, caller-owned toasts and explicit
+feedback/consent callbacks. Native dialog modality and browser accessibility
+remain covered by the existing browser suite; server/unit tests are not a claim
+of complete assistive-technology testing for every new pattern.
+
+## Portal shell
+
+[`PortalLayout`, `PortalHeader` and `SecondaryNav`](PORTAL.md) provide a complete
+Arabic-default portal shell with responsive navigation, breadcrumbs and footer.
+Run the React 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.
+
+
+[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.
+React/Vue native `data-variant` and `data-size` attributes remain supported;
+typed props take precedence. `wrapperProps` customizes the scroll container.
+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 `onSearch` 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
+
+`ContentNavigation` 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). `onCurrentChange(id)` 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.
+
+```tsx
+import {ContentNavigation} from '@hawiyah/react';
+
+<ContentNavigation items={[{id: 'requirements', label: 'المتطلبات'}]} />
+<section id="requirements"><h2>المتطلبات</h2></section>
+```