@ojiepermana/angular 21.3.3 → 22.0.1

package/navigation/topbar/README.md

@@ -0,0 +1,196 @@
+# Topbar
+
+Horizontal navigation root for application shells, documentation headers, and flyout-style site navigation.
+
+## Import
+
+```ts
+import { TopbarComponent } from '@ojiepermana/angular/navigation/topbar';
+import type { NavigationItem, TopbarVariant } from '@ojiepermana/angular/navigation/types';
+```
+
+## Composition
+
+The topbar renders a menubar-style root and projects optional leading and trailing slots around the navigation items.
+
+```text
+topbar
+├── [items]="NavigationItem[]"
+│   ├── type: 'basic' -> direct link item
+│   ├── type: 'group' -> dropdown trigger + overlay panel
+│   └── type: 'collapsable' -> dropdown trigger + overlay panel
+├── `variant="flyout"` -> descriptive title + subtitle cards in dropdown panels
+├── [topbar-start] projected brand or leading actions
+└── [topbar-end] projected trailing actions
+```
+
+## Basic usage
+
+Pass `NavigationItem[]` directly when the page owns its own navigation tree.
+
+```ts
+const navigationItems: NavigationItem[] = [
+  {
+    id: 'getting-started',
+    type: 'group',
+    title: 'Getting started',
+    children: [
+      {
+        id: 'introduction',
+        type: 'basic',
+        title: 'Introduction',
+        subtitle: 'Overview and design-system fundamentals.',
+        link: '/docs/introduction',
+      },
+      {
+        id: 'installation',
+        type: 'basic',
+        title: 'Installation',
+        subtitle: 'Package install and workspace setup steps.',
+        link: '/docs/getting-started/installation',
+      },
+    ],
+  },
+  { id: 'docs', type: 'basic', title: 'Docs', link: '/docs/introduction' },
+];
+```
+
+```html
+<topbar variant="flyout" [items]="navigationItems" [showHamburger]="false" ariaLabel="Primary site navigation">
+  <a topbar-start href="/" class="inline-flex items-center rounded-md px-2 py-2 text-sm font-semibold text-foreground">
+    Acme UI
+  </a>
+
+  <a
+    topbar-end
+    href="/docs/introduction"
+    class="inline-flex h-9 items-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground">
+    Get started
+  </a>
+</topbar>
+```
+
+## Common patterns
+
+### Grouped dropdowns
+
+Use `group` or `collapsable` items when the trigger should open a panel of related destinations.
+
+Set `variant="flyout"` when those dropdown panels should render descriptive title and subtitle cards in a wider flyout layout.
+
+```ts
+const productItems: NavigationItem[] = [
+  {
+    id: 'resources',
+    type: 'group',
+    title: 'Resources',
+    children: [
+      {
+        id: 'guides',
+        type: 'basic',
+        title: 'Guides',
+        subtitle: 'Browse getting started material and implementation notes.',
+        link: '/docs/introduction',
+      },
+      {
+        id: 'api',
+        type: 'basic',
+        title: 'API reference',
+        subtitle: 'Inspect Angular-first component and directive imports by entrypoint.',
+        link: '/docs/components/shadcn/button',
+      },
+      {
+        id: 'releases',
+        type: 'basic',
+        title: 'Releases',
+        subtitle: 'Track published changes, migration notes, and newly added primitives.',
+        link: '/docs/changelog',
+      },
+    ],
+  },
+  { id: 'pricing', type: 'basic', title: 'Pricing', link: '/pricing' },
+];
+```
+
+### Direct link items
+
+Use `basic` items when the top-level item should navigate immediately instead of opening a panel.
+
+```ts
+const linkItems: NavigationItem[] = [
+  { id: 'documentation', type: 'basic', title: 'Documentation', link: '/docs/introduction' },
+  { id: 'components', type: 'basic', title: 'Components', link: '/ui/shadcn/button' },
+  {
+    id: 'github',
+    type: 'basic',
+    title: 'GitHub',
+    link: 'https://github.com/shadcn-ui/ui',
+    externalLink: true,
+    target: '_blank',
+  },
+];
+```
+
+### Shared shell state
+
+When the shell already uses the navigation registry, let the topbar resolve items from `NavigationService` by `navigationId` instead of passing `items` everywhere.
+
+```html
+<topbar navigationId="main" ariaLabel="Primary"></topbar>
+```
+
+## API reference
+
+### `TopbarComponent`
+
+| Input            | Type               | Default             |
+| ---------------- | ------------------ | ------------------- |
+| `items`          | `NavigationItem[]` | `[]`                |
+| `navigationId`   | `string`           | `'main'`            |
+| `variant`        | `TopbarVariant`    | `'default'`         |
+| `ariaLabel`      | `string`           | `'Primary'`         |
+| `class`          | `string`           | `''`                |
+| `autoRegister`   | `boolean`          | `true`              |
+| `showHamburger`  | `boolean`          | `true`              |
+| `hamburgerLabel` | `string`           | `'Open navigation'` |
+
+### Supporting types
+
+- `NavigationItem` is the typed data model for `basic`, `group`, `collapsable`, and related navigation branches.
+- `TopbarVariant` is currently `'default' | 'flyout'`.
+- Lower-level item rendering and shell coordination live in `@ojiepermana/angular/navigation/item` and `@ojiepermana/angular/navigation/service`.
+- In `flyout` mode, `basic` child item `subtitle` values render as supporting description copy inside dropdown cards.
+
+## Styling and theming
+
+The component is sticky by default and uses the shared theme tokens for foreground, accent, focus ring, and dropdown chrome.
+
+- Pass `class` to `topbar` when the shell needs custom border, background, width, or spacing utilities.
+- Style projected `[topbar-start]` and `[topbar-end]` content directly on the projected hosts.
+- For documentation or embedded previews, override the sticky positioning locally with `style="position: static; top: auto;"`.
+- The dropdown panel now uses `border-border` and background theme tokens, with a wider card grid when `variant="flyout"`.
+
+## Accessibility
+
+- The host exposes `role="navigation"`; set `ariaLabel` when multiple navigation landmarks exist on the page.
+- The item list uses `role="menubar"`, and top-level interactive items expose `role="menuitem"`.
+- Direct destinations should stay `basic` items so Angular renders anchors with native link semantics.
+- Keep projected CTA elements keyboard reachable and visually distinct from navigation triggers.
+
+## Keyboard interactions
+
+- Left and Right Arrow move focus across the top-level items.
+- Home and End jump to the first and last top-level item.
+- Down Arrow moves focus into an already-open dropdown panel.
+- Escape closes the active dropdown and returns focus to the trigger.
+
+## Angular notes
+
+- Use `NavigationItem` data or projected slot content to compose shell-level navigation.
+- `autoRegister` keeps `NavigationService` in sync with explicit `items`, so active-trail logic still works when the shell uses the shared registry.
+- Prefer `variant="flyout"` plus `subtitle` on child `basic` items when the goal is descriptive dropdown-card content.
+- Prefer `@ojiepermana/angular/component/navigation-menu` when the page needs explicit trigger/content composition rather than a shell-driven data model.
+
+## Source parity
+
+This entrypoint covers the Angular shell-navigation behavior that matters most for top-level application chrome: a horizontal menubar, grouped dropdown triggers, descriptive dropdown cards in `flyout` mode, direct link items, projected brand and action slots, and shared shell integration. Use the dedicated navigation-menu component entrypoint when the goal is a closer shadcn-style website navigation composition.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ojiepermana/angular",
-  "version": "21.3.3",
+  "version": "22.0.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ojiepermana/angular.git"
@@ -10,12 +10,12 @@
     "url": "https://github.com/ojiepermana/angular/issues"
   },
   "peerDependencies": {
-    "@angular/common": "^21.2.0",
-    "@angular/core": "^21.2.0",
-    "@angular/forms": "^21.2.0",
-    "@angular/router": "^21.2.0",
-    "@angular/cdk": "^21.2.7",
-    "@angular/material": "^21.2.7",
+    "@angular/common": ">=22.0.0",
+    "@angular/core": ">=22.0.0",
+    "@angular/forms": ">=22.0.0",
+    "@angular/router": ">=22.0.0",
+    "@angular/cdk": ">=22.0.0",
+    "@angular/material": ">=22.0.0",
     "rxjs": "^7.8.0",
     "tailwindcss": "^4.3.0"
   },
@@ -34,7 +34,7 @@
     }
   },
   "dependencies": {
-    "@angular-devkit/schematics": "^21.2.7",
+    "@angular-devkit/schematics": "^22.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "d3-array": "^3.2.4",
@@ -52,12 +52,12 @@
   },
   "ng-update": {
     "packageGroup": {
-      "@angular/common": "^21.2.9",
-      "@angular/core": "^21.2.9",
-      "@angular/forms": "^21.2.9",
-      "@angular/router": "^21.2.9",
-      "@angular/cdk": "^21.2.7",
-      "@angular/material": "^21.2.7",
+      "@angular/common": ">=22.0.0",
+      "@angular/core": ">=22.0.0",
+      "@angular/forms": ">=22.0.0",
+      "@angular/router": ">=22.0.0",
+      "@angular/cdk": ">=22.0.0",
+      "@angular/material": ">=22.0.0",
       "rxjs": "~7.8.2",
       "tailwindcss": "^4.3.0"
     }
@@ -175,6 +175,10 @@
       "types": "./types/ojiepermana-angular-component-command.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-command.mjs"
     },
+    "./component/composer": {
+      "types": "./types/ojiepermana-angular-component-composer.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-composer.mjs"
+    },
     "./component/context-menu": {
       "types": "./types/ojiepermana-angular-component-context-menu.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-context-menu.mjs"
@@ -195,10 +199,22 @@
       "types": "./types/ojiepermana-angular-component-dropdown-menu.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-dropdown-menu.mjs"
     },
+    "./component/editor": {
+      "types": "./types/ojiepermana-angular-component-editor.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-editor.mjs"
+    },
+    "./component/empty": {
+      "types": "./types/ojiepermana-angular-component-empty.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-empty.mjs"
+    },
     "./component/form": {
       "types": "./types/ojiepermana-angular-component-form.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-form.mjs"
     },
+    "./component/hover-card": {
+      "types": "./types/ojiepermana-angular-component-hover-card.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-hover-card.mjs"
+    },
     "./component/input": {
       "types": "./types/ojiepermana-angular-component-input.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-input.mjs"
@@ -207,18 +223,46 @@
       "types": "./types/ojiepermana-angular-component-input-group.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-input-group.mjs"
     },
+    "./component/input-otp": {
+      "types": "./types/ojiepermana-angular-component-input-otp.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-input-otp.mjs"
+    },
     "./component/item": {
       "types": "./types/ojiepermana-angular-component-item.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-item.mjs"
     },
+    "./component/kanban": {
+      "types": "./types/ojiepermana-angular-component-kanban.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-kanban.mjs"
+    },
+    "./component/kbd": {
+      "types": "./types/ojiepermana-angular-component-kbd.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-kbd.mjs"
+    },
     "./component/label": {
       "types": "./types/ojiepermana-angular-component-label.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-label.mjs"
     },
+    "./component/menubar": {
+      "types": "./types/ojiepermana-angular-component-menubar.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-menubar.mjs"
+    },
+    "./component/native-select": {
+      "types": "./types/ojiepermana-angular-component-native-select.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-native-select.mjs"
+    },
+    "./component/navigation-menu": {
+      "types": "./types/ojiepermana-angular-component-navigation-menu.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-navigation-menu.mjs"
+    },
     "./component/pagination": {
       "types": "./types/ojiepermana-angular-component-pagination.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-pagination.mjs"
     },
+    "./component/pillbox": {
+      "types": "./types/ojiepermana-angular-component-pillbox.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-pillbox.mjs"
+    },
     "./component/popover": {
       "types": "./types/ojiepermana-angular-component-popover.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-popover.mjs"
@@ -231,6 +275,10 @@
       "types": "./types/ojiepermana-angular-component-radio.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-radio.mjs"
     },
+    "./component/resizable": {
+      "types": "./types/ojiepermana-angular-component-resizable.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-resizable.mjs"
+    },
     "./component/scroll-area": {
       "types": "./types/ojiepermana-angular-component-scroll-area.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-scroll-area.mjs"
@@ -255,6 +303,10 @@
       "types": "./types/ojiepermana-angular-component-slider.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-slider.mjs"
     },
+    "./component/spinner": {
+      "types": "./types/ojiepermana-angular-component-spinner.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-spinner.mjs"
+    },
     "./component/switch": {
       "types": "./types/ojiepermana-angular-component-switch.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-switch.mjs"
@@ -271,10 +323,22 @@
       "types": "./types/ojiepermana-angular-component-textarea.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-textarea.mjs"
     },
+    "./component/timeline": {
+      "types": "./types/ojiepermana-angular-component-timeline.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-timeline.mjs"
+    },
     "./component/toast": {
       "types": "./types/ojiepermana-angular-component-toast.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-toast.mjs"
     },
+    "./component/toggle": {
+      "types": "./types/ojiepermana-angular-component-toggle.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-toggle.mjs"
+    },
+    "./component/toggle-group": {
+      "types": "./types/ojiepermana-angular-component-toggle-group.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-component-toggle-group.mjs"
+    },
     "./component/tooltip": {
       "types": "./types/ojiepermana-angular-component-tooltip.d.ts",
       "default": "./fesm2022/ojiepermana-angular-component-tooltip.mjs"
@@ -295,14 +359,6 @@
       "types": "./types/ojiepermana-angular-layout-component.d.ts",
       "default": "./fesm2022/ojiepermana-angular-layout-component.mjs"
     },
-    "./layout/empty": {
-      "types": "./types/ojiepermana-angular-layout-empty.d.ts",
-      "default": "./fesm2022/ojiepermana-angular-layout-empty.mjs"
-    },
-    "./layout/horizontal": {
-      "types": "./types/ojiepermana-angular-layout-horizontal.d.ts",
-      "default": "./fesm2022/ojiepermana-angular-layout-horizontal.mjs"
-    },
     "./layout/provider": {
       "types": "./types/ojiepermana-angular-layout-provider.d.ts",
       "default": "./fesm2022/ojiepermana-angular-layout-provider.mjs"
@@ -323,9 +379,17 @@
       "types": "./types/ojiepermana-angular-layout-token-directive.d.ts",
       "default": "./fesm2022/ojiepermana-angular-layout-token-directive.mjs"
     },
-    "./layout/vertical": {
-      "types": "./types/ojiepermana-angular-layout-vertical.d.ts",
-      "default": "./fesm2022/ojiepermana-angular-layout-vertical.mjs"
+    "./layout/type/empty": {
+      "types": "./types/ojiepermana-angular-layout-type-empty.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-layout-type-empty.mjs"
+    },
+    "./layout/type/horizontal": {
+      "types": "./types/ojiepermana-angular-layout-type-horizontal.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-layout-type-horizontal.mjs"
+    },
+    "./layout/type/vertical": {
+      "types": "./types/ojiepermana-angular-layout-type-vertical.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-layout-type-vertical.mjs"
     },
     "./navigation/demo-data": {
       "types": "./types/ojiepermana-angular-navigation-demo-data.d.ts",

package/theme/README.md

@@ -39,12 +39,119 @@ export const appConfig = {
 The public import contract stays stable even if the source files inside this
 entrypoint move.
 
+## Typography mapping
+
+shadcn `Typography` maps to semantic HTML plus this theme entrypoint. There is
+no `@ojiepermana/angular/component/typography` secondary entrypoint.
+
+### Import
+
+```css
+@import '@ojiepermana/angular/theme/styles';
+@import 'tailwindcss';
+@import '@ojiepermana/angular/theme/tailwind/theme.css';
+```
+
+### Composition
+
+```text
+article
+├── h1
+├── p.lead
+├── h2 / h3 / h4
+├── p + a
+├── blockquote
+├── ul / ol
+├── code
+└── table
+```
+
+### Basic usage
+
+```html
+<article class="max-w-2xl text-foreground">
+  <h1 class="scroll-m-20 text-4xl font-extrabold tracking-tight text-balance">
+    Taxing Laughter: The Joke Tax Chronicles
+  </h1>
+
+  <p class="text-xl leading-7 text-muted-foreground [&:not(:first-child)]:mt-6">
+    Once upon a time, in a far-off land, there was a very lazy king who spent all day lounging on his throne.
+  </p>
+
+  <h2 class="mt-10 scroll-m-20 border-b border-border pb-2 text-3xl font-semibold tracking-tight first:mt-0">
+    The King's Plan
+  </h2>
+
+  <p class="leading-7 [&:not(:first-child)]:mt-6">
+    The king thought long and hard and came up with
+    <a href="#" class="font-medium text-primary underline underline-offset-4">a brilliant plan</a>.
+  </p>
+
+  <blockquote class="mt-6 border-s-2 border-border ps-6 italic">
+    "After all," he said, "everyone enjoys a good joke."
+  </blockquote>
+</article>
+```
+
+### Common patterns
+
+- Use `text-xl leading-7 text-muted-foreground` for a lead paragraph below the page title.
+- Use `relative rounded bg-muted px-[0.3rem] py-[0.2rem] font-mono text-sm font-semibold` for short inline code.
+- Use `border-border`, `text-start`, and real `scope="col"` headers on data tables.
+- Use logical spacing utilities such as `border-s-2`, `ps-6`, and `ms-6` so the same recipe works in RTL.
+
+### API reference
+
+| Concept      | Local surface                                     | Notes                                                                                        |
+| ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Theme styles | `@ojiepermana/angular/theme` and CSS imports      | Provides the token-backed styles and Tailwind bridge.                                        |
+| Headings     | Native `h1`-`h4` elements                         | Keep the heading hierarchy semantic and style each usage site directly.                      |
+| Body copy    | Native `p`, `blockquote`, `ul`, `ol`, and `table` | Typography stays documentation-first and does not wrap content in custom Angular components. |
+| Inline code  | Native `code`                                     | Use a muted surface and mono text for short snippets.                                        |
+| RTL          | `dir="rtl"` on a wrapping container               | Prefer logical spacing utilities when the layout should mirror.                              |
+
+### Styling and theming
+
+Use token-aware utilities such as `border-border`, `bg-muted`,
+`text-foreground`, `text-muted-foreground`, and `text-primary`. Keep the
+typography classes close to the article or page slice that owns the prose
+instead of centralizing them in a rigid wrapper component.
+
+### Accessibility
+
+- Keep heading levels sequential within an article or documentation page.
+- Preserve native list, table, blockquote, and anchor semantics.
+- Add `scope="col"` to table headers when the table communicates real data.
+- Maintain visible link affordances with contrast and underline offset.
+
+### Keyboard interactions
+
+- Typography relies on native browser behavior for links, selection, scrolling,
+  and table navigation.
+- There is no custom roving-focus or composite widget behavior in this mapping.
+
+### Angular notes
+
+- No TypeScript import is required for typography itself; the runtime surface is
+  semantic HTML plus theme CSS.
+- Keep prose data in component fields, markdown content, or a CMS instead of
+  encoding text into a fake typography component API.
+- Use logical spacing utilities when the content may need right-to-left support.
+
+### Source parity
+
+This entrypoint is the durable Angular-first mapping for shadcn `Typography`.
+It follows the same visual recipes while staying honest about the local API:
+there is no dedicated typography secondary entrypoint, and the authoritative
+consumer guidance lives in the theme entrypoint plus the `ui/shadcn/typography`
+demo page.
+
 ## Source layout
 
 - `public-api.ts` aggregates the granular runtime entrypoints for `@ojiepermana/angular/theme`.
-- `services/src/lib` owns `ThemeService` plus its runtime tests.
-- `provider/src/lib` owns DI provider helpers plus provider-focused tests.
-- `token/src/lib` owns config types, guards, constants, and token-focused tests.
+- `services` owns `ThemeService` plus its runtime tests.
+- `provider` owns DI provider helpers plus provider-focused tests.
+- `token` owns config types, guards, constants, and token-focused tests.
 - `css/foundation` contains the cascade layer registration, shared semantic tokens, and component-facing global helpers.
 - `css/variants/mode` contains light and dark mode layers.
 - `css/variants/color` contains named color themes.