@hawiyah/vue 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,70 @@
+# Portal layout
+
+`PortalLayout` composes `PortalHeader`, optional `SecondaryNav`, `Breadcrumb`,
+a focusable main container and `PortalFooter`. It defaults to `lang="ar" dir="rtl"`.
+
+```vue
+<script setup lang="ts">
+import { PortalLayout } from '@hawiyah/vue';
+import '@hawiyah/styles/styles.css';
+const links = [{ label: 'الخدمات', href: '/services', current: true }];
+</script>
+<template>
+  <PortalLayout brand="هوية" :links="links" :secondary-navigation="links"
+    :breadcrumbs="[{ label: 'الرئيسية', href: '/' }, { label: 'الخدمات', current: true }]"
+    :footer-links="[{ label: 'الخصوصية', href: '/privacy' }]">
+    <h1>الخدمات</h1>
+  </PortalLayout>
+</template>
+```
+
+Props: `brand` (required), `homeHref`, `links`, `secondaryNavigation`, `footerLinks`,
+`breadcrumbs`, `copyright`, `mainId`, `lang`, `dir`. Accessible labels:
+`skipLabel`, `menuLabel`, `navigationLabel`, `secondaryLabel`, `breadcrumbLabel`,
+`footerLabel`. `mainId` uses Vue `useId` by default. Slots: `logo`, `actions`,
+`footer`, default (page content). Supply actual artwork through `logo`.
+
+For English, pass `lang="en" dir="ltr"` and translate all content and labels.
+Direction and language remain independent. Existing standalone `PortalHeader`
+keeps `brand`, `homeHref`, `links`, `navLabel` and its slots, adding `menuLabel`,
+`navigationId`, `mainId` and `skipLabel`. Escape returns focus to the toggle;
+selection, outside press and focus leaving close the mobile disclosure. Tab is
+native. Desktop links remain visible. `SecondaryNav` uses `items`, `label` and
+ordinary page links with `aria-current`, not menu/tablist semantics.
+
+The 48rem mobile breakpoint is Hawiyah policy. Shared tokens preserve DGA, Hawiyah
+and custom themes. The shell introduces no animations. Source-informed
+composition does not establish 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,389 @@
-# Temporary Holding Version
+# @hawiyah/vue
 
-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 Vue 3 components for Hawiyah — هوية, a UI library built to comply with the
+DGA Platforms Code.
+Install with `npm install @hawiyah/styles @hawiyah/vue`. This is a pre-1.0 release,
+so a minor version may still change its API. Import the shared CSS once:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Button, Combobox, Dialog, TextField } from "@hawiyah/vue";
+import "@hawiyah/styles/styles.css";
+// Optional for a new application: import '@hawiyah/styles/reset.css';
+const name = ref("");
+const city = ref("");
+const reviewing = ref(false);
+const cities = [{ value: "riyadh", label: "الرياض" }];
+</script>
+
+<template>
+  <form dir="rtl" lang="ar" @submit.prevent="reviewing = true">
+    <TextField v-model="name" label="الاسم" name="name" required />
+    <Combobox
+      v-model="city"
+      :options="cities"
+      label="المدينة"
+      name="city"
+      required
+      empty-message="لا توجد نتائج"
+      required-message="اختر مدينة من القائمة."
+      :results-message="(count) => `${count} نتائج متاحة`"
+    />
+    <Button type="submit">مراجعة</Button>
+  </form>
+  <Dialog v-model:open="reviewing" title="مراجعة الطلب" close-label="إغلاق">
+    <p>{{ name }}</p>
+    <template #footer="{ close }"><Button @click="close">تم</Button></template>
+  </Dialog>
+</template>
+```
+
+## Conventions
+
+Components use native elements and Vue rendering. They share core keyboard and
+combobox transitions without importing another adapter. Vue `useId()` supplies
+server/client stable accessible IDs; importing or server-rendering the package
+does not access browser globals. Vue 3.5+ and native `<dialog>` support are required.
+A server-rendered open dialog becomes modal after mounting.
+
+Native attributes and event listeners fall through to the primary control. Classes
+are merged, and internal event handlers preserve consumer listeners. Field controls
+expose `element` and `focus()` through a Vue template ref; `Button` does too.
+`Dialog` exposes `element`, `show()` and `close()`. `Combobox` adds `close()`.
+
+Text inputs, select, combobox, tabs and pagination use `v-model`; omitting it
+uses internal state initialized by `defaultValue`. Checkbox/switch values are
+booleans; radio values are strings matched against the radio's `value` prop.
+`Dialog` uses `v-model:open` / `defaultOpen`. Form reset emits model defaults so
+both controlled and uncontrolled controls can return to their initial state.
+Use `defaultValue` alongside `v-model` if a nonempty reset value is desired.
+
+For radios sharing a form and `name`, set `defaultValue` to the option that
+should be checked after a reset. The group emits that value once. A group
+without a checked default resets to an empty string.
+
+Locale, direction, theme, mode and density are independent application choices.
+Set `lang`, `dir`, `data-hw-theme="hawiyah|dga|custom"`,
+`data-hw-mode="light|dark"` and `data-hw-density="comfortable|compact|mobile"` on an
+ancestor. Provide translated labels, status messages, pagination labels and
+close labels; the library never infers text language from layout direction.
+
+## Catalog
+
+| Export                  | Main contract                                                                                                                                                         |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Button`                | `variant`, `size`, `loading`; defaults to `type="button"`                                                                                                             |
+| `Field`                 | `label`, `hint`, `error`, `required`, `controlId`; provides association to a child field control; scoped default slot exposes IDs for native controls                 |
+| `TextField`, `Textarea` | String `v-model`, `defaultValue`, field decoration; standard input/textarea attributes                                                                                |
+| `Select`                | String `v-model`, `options: Option[]`; native option children also accepted                                                                                           |
+| `Checkbox`, `Switch`    | Boolean `v-model`, `defaultValue`, label/hint/error; checkbox supports `indeterminate`                                                                                |
+| `Radio`                 | String `v-model`, `value`, shared native `name`; group inside a fieldset with a legend                                                                                |
+| `Combobox`              | String `v-model`, `options`, `disabled`, `readonly`, `emptyMessage`, `resultsMessage(count)`, `requiredMessage`; emits `update:query`, `update:open`                  |
+| `Tabs`                  | `items`, required `label`, string `v-model`, `orientation`, `activationMode`, `overflow: menu/scroll` (default menu), configurable `overflowLabel`; item content or named value slots, optional `tab:value` label slots. Compact horizontal containers move excess labels into a keyboard-accessible disclosure; vertical tabs remain visible. |
+| `Dialog`                | `title`, `description`, `closeLabel`, `closeOnBackdrop`; default/footer slots receive `{close}`, trigger slot receives `{open}`                                       |
+| `Accordion`             | `items: {value,title,content?,open?}[]`, `exclusive`; native details, named value content slots; emits `toggle(value,open)`                                           |
+| `Card`                  | `header`, default and `footer` slots                                                                                                                                  |
+| `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`, `title`; defaults to status, or alert for danger; native role can override |
+| `Table`                 | `columns`, `rows`, `rowKey`, `caption`; column `{key,header,cell?,rowHeader?}`; named `cell:key` slots receive `{row,index}`; omit columns to compose native children |
+| `Pagination` | Numeric `v-model`/`defaultValue`, `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`            | `items: {label,href?,current?}[]`, `label`                                                                                                                            |
+| `Progress`              | Required `label`, optional value for determinate mode, `max=100`                                                                                                      |
+| `Skeleton`              | Decorative hidden span, size using native style/class                                                                                                                 |
+| `Spinner`               | Status with localized `label`                                                                                                                                         |
+| `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 `hr`                                                                                                                                                           |
+| `Tooltip`               | Plain `content`, one focusable trigger in default slot; description IDs merge with the trigger                                                                        |
+| `FileUpload`            | Native input attributes plus field decoration; emits `update:files(File[])`; optional default slot                                                                    |
+| `Stepper`               | `items: {value,label,description?,status?}[]`, `current`, `label`                                                                                                     |
+| `EmptyState`            | `title`, `description`; `icon`, default, `action` slots                                                                                                               |
+
+`Field` associates one control; use a native fieldset and legend for groups.
+Combobox is local, editable, single selection: editing clears the submitted value,
+arrow keys skip disabled options, Enter commits explicitly, Escape/Tab/blur/outside
+close without committing. `name` is attached to a hidden input containing the
+selected option value. Required validation checks selection, not merely typed text.
+Readonly comboboxes never open or change selection. Tabs use roving focus and
+RTL-aware horizontal arrows; manual mode selects through native Enter/Space.
+Dialog uses `showModal()` / `close()` for browser modality and focus containment,
+then returns focus to its connected opener. Tooltips must not contain interactive
+content; use a dialog for interactive help.
+
+The example in `examples/vue` includes independent locale/direction/theme controls,
+a conditional service form, validation, native modal review, local request filtering
+and pagination, and the remaining presentation components. Unit tests exercise
+behavior and server rendering; browser checks validate the application workflow.
+
+## Expanded controls
+
+The package now exports **77 components**: the original 27 and these 50 additions.
+All use native Vue rendering, shared CSS, and the same attrs/slots conventions.
+
+| Component       | Props, models and events                                                                                                                                                                                                                                                                                                                       |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `InputGroup`    | `prefix`, default and `suffix` slots; the consuming field supplies its label                                                                                                                                                                                                                                                                   |
+| `PasswordField` | String `v-model`, `defaultValue`, field decoration, `disabled`, `readonly`; `showLabel`, `hideLabel` localize the reveal button; input and button form one input group                                                                                                                                                                         |
+| `SearchField`   | String `v-model`, `defaultValue`, field decoration, `clearLabel`; optional `suggestions`, `maxSuggestions` (8), `resultsMessage(count)`, `showSearchButton` (false), `searchLabel`; emits `search(query)`. Input attributes and exposed `element`/`focus()` remain supported. |
+| `NumberField`   | `v-model: number \| ''`; native `min`, `max`, `step` and `required`; clearing preserves an empty value instead of inventing zero                                                                                                                                                                                                               |
+| `Slider`        | Numeric `v-model`, `defaultValue`, `min=0`, `max=100`, `step=1`, field decoration, `disabled`, `readonly`; native range keyboard behavior                                                                                                                                                                                                      |
+| `RangeSlider`   | Tuple `v-model: readonly [number,number]`, `defaultValue`, `min`, `max`, `step`; `label`, `lowerLabel`, `upperLabel`, `lowerName`, `upperName`; two native ranges enforce lower ≤ upper                                                                                                                                                        |
+| `Rating`        | Numeric `v-model`, `defaultValue`, `max=5` (1–20), native `name`, `required`, `label`, `hint`, `error`, `disabled`, `readonly`; `optionLabel(value,max)` localizes each native radio                                                                                                                                                           |
+| `RatingDisplay` | 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 `v-model`, `length=6`, field decoration; one input with `one-time-code`, numeric keyboard, native length/pattern; normalizes Arabic-Indic/Eastern digits; emits `complete(value)`                                                                                                                                                       |
+| `TagInput`      | String-array `v-model`, `defaultValue`, `name`, `required`, field decoration; Enter/comma adds unique trimmed tags; Backspace on an empty draft removes the last tag; `removeLabel(value)`, `requiredMessage`                                                                                                                                  |
+| `MultiSelect`   | String-array `v-model`, `defaultValue`, `options`, `label`, `searchLabel`, `emptyMessage`, `requiredMessage`; normalized search and native checkboxes, repeated hidden values for `name`; no combobox role                                                                                                                                     |
+| `Calendar`      | ISO-string `v-model`, `defaultValue`, `month`, `min`, `max`, `locale`, `calendar`, `weekStartsOn`, `isDateDisabled(value)`; `label`, `previousLabel`, `nextLabel`, `unsupportedMessage`; emits `update:month` when browsing                                                                                                                    |
+| `DatePicker`    | Calendar props plus field decoration and string `v-model`; custom ISO text input and modal Calendar; `v-model:calendar` switches `gregory` / `islamic-umalqura` while preserving ISO value; `calendarSwitchable=true`, `calendarSystemLabel`, `gregoryLabel`, `hijriLabel`, `calendarLabel`, `openLabel`, `closeLabel`, `invalidMessage` |
+| `FileDropzone`  | Field decoration, native `name`/`form`, `accept`, `multiple`, `maxSize` in bytes, `disabled`, `readonly`, `dropLabel`; emits `update:files(File[])` and `reject(File[])`; valid drops populate the native file input, invalid batches clear it                                                                                                 |
+
+Value controls support form reset. Arrays reset to `defaultValue`; native file
+controls reset to no files. `TagInput` and `MultiSelect` validate committed
+selection rather than draft/search text. Supply localized validity messages.
+Native attributes such as `name`, `form`, `autocomplete` and `inputmode` pass to
+the control, except that compound controls explicitly manage successful values.
+
+`TextField` remains available for standard HTML input types: `text`, `email`,
+`url`, `tel`, `password`, `search`, `date`, `time`, `month`, `week`,
+`datetime-local`, `color`, and others supported by the browser. It uses a string
+model and preserves native input semantics. Use `NumberField` for numeric/empty
+values, `FileUpload`/`FileDropzone` for File objects, and the native choice/range
+components for their specialized models. Native date/time values are machine
+values, independent of localized browser display; `datetime-local` contains no
+time-zone information.
+
+### Switching date systems
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { DatePicker } from "@hawiyah/vue";
+import type { CalendarSystem } from "@hawiyah/core";
+const date = ref("2024-03-11");
+const system = ref<CalendarSystem>("islamic-umalqura");
+</script>
+
+<template>
+  <DatePicker
+    v-model="date"
+    v-model:calendar="system"
+    name="appointment"
+    label="تاريخ الموعد"
+    locale="ar-SA"
+    dir="rtl"
+    required
+    calendar-label="اختر تاريخ الموعد"
+    calendar-system-label="نوع التقويم"
+    gregory-label="ميلادي"
+    hijri-label="أم القرى"
+    open-label="فتح التقويم"
+    close-label="إغلاق"
+    previous-label="الشهر السابق"
+    next-label="الشهر التالي"
+    invalid-message="اختر تاريخاً متاحاً."
+    unsupported-message="التاريخ خارج نطاق بيانات تقويم أم القرى المدعومة."
+  />
+</template>
+```
+
+The default Arabic locale supplies calendar navigation, picker control labels and validation messages. Set `locale="en"` for English or override individual labels through props.
+
+The stored/submitted value stays Gregorian `YYYY-MM-DD` when switching display
+calendars. Reopening shows the selected date's month. Calendar supports arrows
+(horizontal direction follows RTL/LTR), Home/End, PageUp/PageDown, and
+Shift+PageUp/PageDown for years. Selection uses native Enter/Space button behavior.
+Disabled dates are skipped, min/max are enforced, and readonly calendars allow
+browsing without changing the selected value.
+
+Saudi Umm al-Qura conversion and arithmetic come from the core's pinned Saudi
+reference table, using `@internationalized/date` arithmetic. The supported range
+is **AH 1343–1500, Gregorian 1924-08-01 through 2077-11-16**. Numeric day/year
+values and accessible date names use the same provider through
+`formatCalendarDate`; browser ICU supplies localized names and formatting, not
+an alternative numeric conversion. Navigation stops at supported boundaries.
+Switching an existing out-of-range Gregorian value does not rewrite it: the
+picker displays the caller-localized unsupported message and native validation
+rejects it until the user chooses a supported date or switches back. See the
+core calendar documentation for provenance and coverage; this is not an official
+endorsement or a claim about religious moon-sighting determinations.
+
+## Expanded interactions
+
+| Component     | Contract                                                                                                                                                                                                                                                                               |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ToggleGroup` | `options`, `label`, `variant: segmented\|outline`; string `v-model` uses native radio selection; `multiple` uses string-array `v-model` and pressed buttons; `defaultValue`, native `name`/`form`, `disabled`, `readonly`                                                              |
+| `Popover`     | `label`, `triggerLabel`, `v-model:open` / `defaultOpen`, `disabled`; optional trigger content slot; default slot `{close}`; labelled region, ordinary Tab navigation, outside press and Escape dismissal                                                                               |
+| `Menu`        | `label`, `items: {value,label,disabled?,href?}[]`; optional trigger content slot; emits `select(value)`; Home/End/ArrowUp/ArrowDown skip disabled items, Escape returns focus, Tab exits normally                                                                                      |
+| `Drawer`      | Dialog API with `side: start\|end\|bottom`; modal native dialog and preserved trigger focus; default/footer/trigger scoped slots inherited                                                                                                                                             |
+| `ToastRegion` | `messages: {id,title?,message,tone?,urgent?,dismissible?}[]`, `label`, `dismissLabel(message)`, `@dismiss="remove"`. Set `variant="banner"` and optionally `position="inline"` or a corner. A dismissal listener enables the close action. Defaults are Arabic. |
+| `Collapsible` | `label`, boolean `v-model`, `defaultValue`, `disabled`; native details/summary with default content slot                                                                                                                                                                               |
+| `TreeView`    | `items: {id,label,disabled?,children?}[]`, `label`, selected-id `v-model`, `defaultValue`, `v-model:expanded`, `defaultExpanded`, `disabled`; localized `expandLabel(node)` / `collapseLabel(node)`; flattened visible tree with level/position, roving focus and RTL expansion arrows |
+| `Carousel` | Required label/slides; `v-model/defaultValue`, `wrap=true`, `slides` and named slide-ID slots, one-based `slideMessage(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). |
+
+Popover is a disclosure, not a focus trap. Menu is for commands/navigation;
+TreeView does not claim drag-and-drop. Toast and notification dismissal is
+caller-owned: update the supplied message array in response to the emitted ID.
+
+## Expanded content and platform patterns
+
+| Component          | Contract                                                                                                                                                                                                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Link`             | Native anchor attrs, `href`, `disabled`, `external`; external links use `noopener noreferrer`                                                                                                                                                                                              |
+| `IconButton`       | Required accessible `label`, `variant`, `size`, `disabled`, `loading`; default decorative icon slot                                                                                                                                                                                        |
+| `ButtonGroup`      | Required `label`; default buttons slot; native `data-variant` / `data-orientation` for shared CSS variants                                                                                                                                                                                 |
+| `Chip`             | `label` or default slot, `tone`, `removable`, `removeLabel`, `disabled`; emits `remove`                                                                                                                                                                                                    |
+| `DescriptionList`  | `items: {term,description}[]`, `variant: stacked\|horizontal\|compact`; `item:index` slots receive `{item}`                                                                                                                                                                                |
+| `Stat`             | `label`, string/number `value`, `locale`, `description`, `trend`; numeric values format with Intl                                                                                                                                                                                          |
+| `Timeline`         | `label`, `items: {id,title,description?,date?,dateLabel?,status?}[]`; named item-ID slots; machine-readable native time, optional current step                                                                                                                                             |
+| `Meter`            | Required `label`, `value`; native `min`, `max`, `low`, `high`, `optimum` semantics                                                                                                                                                                                                         |
+| `AvatarGroup`      | `label`, `items: {name,src?,initials?}[]`, `max`, `remainingLabel(count)`                                                                                                                                                                                                                  |
+| `DataTable`        | `caption`, `rows: Record<string,unknown>[]`, `columns: {key,label,sortable?,rowHeader?}[]`, `rowKey`, `locale`; `v-model:sort-key`, `v-model:sort-direction`, initial `defaultSortKey` / `defaultSortDirection`; `sortLabel(column,nextDirection)`; `cell:key` slots receive `{row,index}` |
+| `ServiceCard`      | `title`, `description`, `href`, `actionLabel`, `badge`, `metadata`; `icon`, default and `action` slots                                                                                                                                                                                     |
+| `ServiceDetails`   | `title`, `description`, DescriptionList `items`; default and `action` slots                                                                                                                                                                                                                |
+| `PortalHeader`     | `brand`, `homeHref`, `links: {label,href,current?}[]`, `navLabel`; `logo`, `actions`, default slots Optional top-level `groups` contain a label and child links. See [grouped navigation](../../docs/nic-portal-navigation.md). |
+| `PortalFooter`     | `brand`, `copyright`, `links`, `navLabel`; default content slot                                                                                                                                                                                                                            |
+| `Feedback`         | `label`, selected answer string `v-model` (`yes`/`no`), `defaultValue`, `yesLabel`, `noLabel`, `commentLabel`, `submitLabel`, `thanks`, `disabled`, `readonly`; emits `submit({value,comment})`                                                                                            |
+| `CookieConsent`    | `v-model:open`, `defaultOpen=true`, `label`, required `description`, `acceptLabel`, `rejectLabel`, `preferencesLabel`; emits `accept`, `reject`, `preferences`; no hidden storage or third-party initialization                                                                            |
+| `NotificationList` | `label`, `items: {id,title,description?,date?,dateLabel?,read?,href?}[]`, `emptyMessage`, `readLabel(item)`, `dismissLabel(item)`; emits `read(id)`, `dismiss(id)`; named ID slots                                                                                                         |
+
+DataTable sorting is immutable, stable and localized. It remains a native table;
+use the existing Table component for unrestricted table composition. Platform
+patterns render content supplied by the application: no government seals, trust
+verification, identity verification, analytics or backend service are implied.
+Feedback emits data for the consuming application to persist; CookieConsent
+emits decisions for the application to enforce and persist.
+
+## Layout primitives
+
+All layout primitives forward native HTML attributes and accept `as` (default
+`div`, or `section` for Section). Shared `LayoutProps` includes:
+
+- `gap` and `padding`: token numbers 0–16 or CSS length strings, optionally
+  responsive `{base,sm,md,lg,xl}` objects.
+- `align: start|center|end|stretch|baseline`,
+  `justify: start|center|end|between|around|evenly`, and `wrap`.
+- `columns`: a positive number or responsive object; `minItemWidth` opts into
+  adaptive auto-fit columns instead.
+- `side: start|end`, `sidebarWidth`, `collapseAt: sm|md|lg`, `maxWidth`, `ratio`.
+
+| Component     | Composition                                                                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `Container`   | Constrained centered content, optional `maxWidth`                                                                     |
+| `Stack`       | Vertical flex layout                                                                                                  |
+| `Inline`      | Horizontal flex layout with optional wrapping                                                                         |
+| `Grid`        | Responsive explicit or adaptive grid                                                                                  |
+| `Columns`     | Same grid contract with a column-composition semantic name                                                            |
+| `Sidebar`     | First child is sidebar, second child is main content; `side` changes visual placement, `collapseAt` controls stacking |
+| `Center`      | Centered flex content                                                                                                 |
+| `Spacer`      | Flexible empty space; keep decorative                                                                                 |
+| `AspectRatio` | Media frame with positive `ratio`, e.g. `16 / 9`                                                                      |
+| `Section`     | Semantic section; name it with native `aria-label` or a heading                                                       |
+| `AppShell`    | Use `header`, `sidebar`, default main content and `footer` slots. The Arabic skip link focuses main. Set `mainId` to choose its target ID and `skipLabel` to localize the link. |
+| `PageHeader`  | `title`, `description`, heading `level=1`; `breadcrumb`, `actions`, default slots; outer element is always header     |
+
+```vue
+<Container max-width="72rem">
+  <Stack :gap="{ base: 4, lg: 8 }">
+    <PageHeader title="خدماتك" description="اختر الخدمة المناسبة">
+      <template #actions><Button>طلب جديد</Button></template>
+    </PageHeader>
+    <Grid :columns="{ base: 1, md: 2, lg: 3 }" :gap="4">
+      <ServiceCard title="تجديد طلب" description="راجع التفاصيل ثم قدّم الطلب."
+        href="/services/renew" action-label="بدء الخدمة" />
+      <ServiceCard title="متابعة طلب" href="/requests" action-label="عرض الطلبات" />
+    </Grid>
+  </Stack>
+</Container>
+```
+
+Breakpoints are CSS-only: sm 40rem, md 48rem, lg 64rem, xl 80rem. Server and
+client emit identical custom properties through shared `layoutStyles`; no
+viewport measurements or hydration-dependent layout branches are used.
+
+Maps, rich text, charting, code editors, PDF viewers, CAPTCHA and payments are
+integration boundaries. Mount the chosen provider in a named Section/Card or
+AspectRatio with its own accessible fallback and documented data contract. Hawiyah
+does not simulate these engines or handle provider credentials or transactions.
+
+## Portal shell
+
+[`PortalLayout`, `PortalHeader` and `SecondaryNav`](PORTAL.md) provide a complete
+Arabic-default portal shell with responsive navigation, breadcrumbs and footer.
+Run the Vue 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.
+# Native choice read-only state
+
+`Checkbox`, `Radio` and `Switch` accept `readOnly` (`read-only` in templates).
+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.
+React/Vue native `data-variant` and `data-size` attributes remain supported;
+typed props take precedence. `wrapperProps` customizes the scroll container.
+The default sort-action label is Arabic; pass `sortLabel` for another language.
+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 `search` 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). `@current-change="onCurrentChange"` 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.
+
+```vue
+<script setup>
+import {ContentNavigation} from '@hawiyah/vue';
+const sections = [{id: 'requirements', label: 'المتطلبات'}];
+</script>
+<template>
+  <ContentNavigation :items="sections" />
+  <section id="requirements"><h2>المتطلبات</h2></section>
+</template>
+```