@simplysm/angular 14.0.1 → 14.0.5

package/docs/hooks-and-utilities.md

@@ -0,0 +1,175 @@
+# Hooks & Utilities
+
+Hook functions (prefixed with `use`) must be called within Angular injection context (constructor or `runInInjectionContext`).
+
+## `usePermsSignal`
+
+Returns a signal of permitted keys for the given view codes. Filters `permKeys` by checking the app structure's permission record.
+
+```typescript
+function usePermsSignal<K extends string>(viewCodes: string[], keys: K[]): Signal<K[]>;
+```
+
+## `useSdSystemConfigResource`
+
+Creates a resource for reading and writing system configuration values, scoped by the host element's tag name.
+
+```typescript
+function useSdSystemConfigResource<T>(options: {
+  key: Signal<string | undefined>;
+}): {
+  value: Signal<T | undefined>;
+  isLoading: Signal<boolean>;
+  status: Signal<ResourceStatus>;
+  hasValue(): boolean;
+  reload(): void;
+  set(value: T | undefined): void;
+  update(fn: (prev: T | undefined) => T | undefined): void;
+};
+```
+
+## `useCurrentPageCodeSignal`
+
+Returns a signal of the current page code derived from the activated route's URL segments (joined by `.`). Returns `undefined` if no ActivatedRoute is available.
+
+```typescript
+function useCurrentPageCodeSignal(): Signal<string> | undefined;
+```
+
+## `useFullPageCodeSignal`
+
+Returns a signal of the full page code derived from the router's current URL. Updated on every `NavigationEnd`.
+
+```typescript
+function useFullPageCodeSignal(): Signal<string>;
+```
+
+## `useViewTitleSignal`
+
+Returns a signal of the current view's title. Uses modal title if inside a modal, otherwise derives from app structure using the page code.
+
+```typescript
+function useViewTitleSignal(): Signal<string>;
+```
+
+## `useViewTypeSignal`
+
+Returns a signal indicating whether the current view is displayed as a page, modal, or embedded control.
+
+```typescript
+function useViewTypeSignal(getComp: () => object): Signal<TSdViewType>;
+```
+
+### `TSdViewType`
+
+```typescript
+type TSdViewType = "page" | "modal" | "control";
+```
+
+## `useExpandingManager`
+
+Manages tree expand/collapse state for hierarchical data. Computes flattened display items, tracks expanded items, and provides toggle/visibility methods.
+
+```typescript
+function useExpandingManager<T>(binding: {
+  items: Signal<T[]>;
+  expandedItems: WritableSignal<T[]>;
+  getChildrenFn: Signal<((item: T, index: number) => T[] | undefined) | undefined>;
+  sort: (items: T[]) => T[];
+}): {
+  displayItems: Signal<T[]>;
+  hasExpandable: Signal<boolean>;
+  isAllExpanded: Signal<boolean>;
+  toggle(item: T): void;
+  toggleAll(): void;
+  isVisible(item: T): boolean;
+  def(item: T): IExpandItemDef<T>;
+};
+```
+
+### `IExpandItemDef`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `item` | `T` | The data item |
+| `parentDef` | `IExpandItemDef<T> \| undefined` | Parent definition (for tree traversal) |
+| `hasChildren` | `boolean` | Whether item has children |
+| `depth` | `number` | Nesting depth (0-based) |
+
+## `useSelectionManager`
+
+Manages item selection state (single or multi mode). Provides select/deselect/toggle operations and computed selection state.
+
+```typescript
+function useSelectionManager<T>(options: {
+  displayItems: Signal<T[]>;
+  selectedItems: WritableSignal<T[]>;
+  selectMode: Signal<"single" | "multi" | undefined>;
+  getItemSelectableFn: Signal<((item: T) => boolean | string) | undefined>;
+}): {
+  hasSelectable: Signal<boolean>;
+  isAllSelected: Signal<boolean>;
+  getSelectable(item: T): true | string | undefined;
+  getCanChangeFn(item: T): () => boolean;
+  select(item: T): void;
+  deselect(item: T): void;
+  toggle(item: T): void;
+  toggleAll(): void;
+  isSelected(item: T): boolean;
+};
+```
+
+## `useSortingManager`
+
+Manages column sorting state with single and multi-column support. Toggle cycles through: ascending, descending, removed.
+
+```typescript
+function useSortingManager(options: {
+  sorts: WritableSignal<ISortingDef[]>;
+}): {
+  defMap: Signal<Map<string, { indexText?: string; desc: boolean }>>;
+  toggle(key: string, multiple: boolean): void;
+  sort<T>(items: T[]): T[];
+};
+```
+
+### `ISortingDef`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | Column/property key to sort by |
+| `desc` | `boolean` | Whether sort is descending |
+
+## `setSafeStyle`
+
+Safely sets multiple CSS style properties on an element via Renderer2.
+
+```typescript
+function setSafeStyle(
+  renderer: Renderer2,
+  el: HTMLElement,
+  style: Partial<CSSStyleDeclaration>,
+): void;
+```
+
+## `TDirectiveInputSignals`
+
+Utility type that extracts `InputSignal` value types from a component/directive. Non-InputSignal properties are excluded. Properties with `undefined` in their type become optional.
+
+```typescript
+type TDirectiveInputSignals<T> = TUndefToOptional<{
+  [P in keyof T as T[P] extends InputSignal<any> ? P : never]: T[P] extends InputSignal<infer V> ? V : never;
+}>;
+```
+
+## `TUndefToOptional`
+
+Utility type that converts properties containing `undefined` in their type to optional properties.
+
+```typescript
+type TUndefToOptional<T> = {
+  [K in keyof T as undefined extends T[K] ? never : K]: T[K];
+} & {
+  [K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
+};
+```

package/docs/layout-components.md

@@ -0,0 +1,140 @@
+# Layout Components
+
+## `SdDockContainerControl`
+
+Container for docked panels. Calculates padding based on child dock sizes and positions.
+
+Selector: `sd-dock-container`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `contentClass` | `string` | CSS class for the content wrapper |
+
+## `SdDockControl`
+
+Dockable panel that attaches to a side of `SdDockContainerControl`. Supports optional user-resizing with config persistence.
+
+Selector: `sd-dock`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | Config key for size persistence |
+| `position` | `"top" \| "bottom" \| "right" \| "left"` | Dock position (default: `"top"`) |
+| `resizable` | `boolean` (booleanAttribute) | Enable drag-to-resize (default: `false`) |
+
+## `SdPaneDirective`
+
+Applies fill-area pane styling to the host element. Sets CSS class `fill` and `display: block`.
+
+Selector: `sd-pane`, `[sd-pane]`
+
+No inputs.
+
+## `SdGapControl`
+
+Spacing element that renders as a gap with preset or pixel-based dimensions.
+
+Selector: `sd-gap`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `height` | `"xxs" \| "xs" \| "sm" \| "default" \| "lg" \| "xl" \| "xxl"` | Preset height |
+| `heightPx` | `number` | Height in pixels |
+| `width` | `"xxs" \| "xs" \| "sm" \| "default" \| "lg" \| "xl" \| "xxl"` | Preset width |
+| `widthPx` | `number` | Width in pixels |
+| `widthEm` | `number` | Width in em units |
+
+## `SdViewControl`
+
+View container for tab-like content switching. Shows the child `SdViewItemControl` whose value matches.
+
+Selector: `sd-view`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `value` | `any` | Currently active view value |
+| `fill` | `boolean` (booleanAttribute) | Whether to fill parent height (default: `false`) |
+
+## `SdViewItemControl`
+
+Individual view item, shown when its value matches the parent `SdViewControl` value.
+
+Selector: `sd-view-item`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `value` | `any` | Value to match against parent |
+
+## `SdCardDirective`
+
+Applies card styling (CSS class `card`).
+
+Selector: `sd-card`, `[sd-card]`
+
+No inputs.
+
+## `SdKanbanBoardControl`
+
+Kanban board container with drag-and-drop support. Manages drag state and emits drop events.
+
+Selector: `sd-kanban-board`
+
+| Input/Model | Type | Description |
+|-------------|------|-------------|
+| `selectedValues` (model) | `T[]` | Currently selected kanban values (default: `[]`) |
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `drop` | `ISdKanbanBoardDropInfo<L, T>` | Emitted when a kanban card is dropped |
+
+### `ISdKanbanBoardDropInfo`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sourceKanbanValue` | `T` | Value of the dragged card |
+| `targetLaneValue` | `L` | Value of the target lane |
+| `targetKanbanValue` | `T` | Value of the target card (drop position) |
+
+### `ISdKanbanDragRef`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `value()` | `T \| undefined` | Value of the dragged card |
+| `heightOnDrag()` | `number` | Height of the card being dragged |
+
+### `ISdKanbanDropTarget`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `targetLaneValue()` | `L \| undefined` | Value of the target lane |
+| `targetKanbanValue?()` | `T \| undefined` | Value of the target card position |
+
+## `SdKanbanLaneControl`
+
+Kanban lane (column). Contains kanban cards and supports drag-drop targeting, collapse, and select-all.
+
+Selector: `sd-kanban-lane`
+
+| Input/Model | Type | Description |
+|-------------|------|-------------|
+| `busy` | `boolean` (booleanAttribute) | Show busy indicator (default: `false`) |
+| `useCollapse` | `boolean` (booleanAttribute) | Enable collapse toggle (default: `false`) |
+| `collapse` (model) | `boolean` | Collapse state (default: `false`) |
+| `value` | `L` | Lane value identifier |
+
+Content children:
+- `#toolTpl` template: Tool bar content
+- `#titleTpl` template: Title content
+
+## `SdKanbanControl`
+
+Kanban card item within a lane. Supports dragging and selection.
+
+Selector: `sd-kanban`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `value` | `T` | Card value identifier |
+| `selectable` | `boolean` (booleanAttribute) | Enable shift-click selection (default: `false`) |
+| `draggable` | `boolean` (booleanAttribute) | Enable drag-and-drop (default: `false`) |
+| `contentClass` | `string` | CSS class for the card content |

package/docs/navigation-components.md

@@ -0,0 +1,200 @@
+# Navigation Components
+
+## `SdCollapseControl`
+
+Animated collapsible content using negative margin-top transition.
+
+Selector: `sd-collapse`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `open` | `boolean` (booleanAttribute) | Whether content is visible (default: `false`) |
+
+## `SdCollapseIconControl`
+
+Rotating chevron icon that indicates collapse/expand state.
+
+Selector: `sd-collapse-icon`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `open` | `boolean` (booleanAttribute) | Whether in open state (default: `false`) |
+| `openRotate` | `number` (numberAttribute) | Rotation angle in degrees when open (default: `90`) |
+
+## `SdTabControl`
+
+Tab header container. Manages the active tab value.
+
+Selector: `sd-tab`
+
+| Input/Model | Type | Description |
+|-------------|------|-------------|
+| `value` (model) | `any` | Currently active tab value |
+
+## `SdTabItemControl`
+
+Individual tab header item inside `SdTabControl`.
+
+Selector: `sd-tab-item`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `value` | `any` | Tab value (matched against parent's value) |
+
+## `SdTabviewControl`
+
+Combined tab header and content view. Automatically renders tab headers from `SdTabviewItemControl` children.
+
+Selector: `sd-tabview`
+
+| Input/Model | Type | Description |
+|-------------|------|-------------|
+| `value` (model) | `T` | Currently active tabview value |
+
+## `SdTabviewItemControl`
+
+Tab content panel inside `SdTabviewControl`. Shown when its value matches the parent's value.
+
+Selector: `sd-tabview-item`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `value` | `T` (required) | Panel value |
+| `header` | `string` | Tab header text (falls back to value if not set) |
+
+## `SdPaginationControl`
+
+Page navigation with first/prev-group/next-group/last buttons.
+
+Selector: `sd-pagination`
+
+| Input/Model | Type | Description |
+|-------------|------|-------------|
+| `currentPage` (model) | `number` | Current page index, 0-based (default: `0`) |
+| `totalPageCount` | `number` (numberAttribute) | Total number of pages (default: `0`) |
+| `visiblePageCount` | `number` (numberAttribute) | Pages shown per group (default: `10`) |
+
+Public methods:
+
+```typescript
+goToPage(page: number): void;
+goToNextGroup(): void;
+goToPrevGroup(): void;
+goToFirst(): void;
+goToLast(): void;
+```
+
+## `SdSidebarContainerControl`
+
+Layout container with sidebar toggle support. Handles backdrop click and auto-close on navigation.
+
+Selector: `sd-sidebar-container`
+
+Public properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `toggle` | `WritableSignal<boolean>` | Sidebar toggle state |
+
+## `SdSidebarControl`
+
+Sidebar panel that slides in/out. Positioned absolutely on the left side. Responsive: slides from left on mobile.
+
+Selector: `sd-sidebar`
+
+No inputs. Toggle state is derived from parent `SdSidebarContainerControl`.
+
+## `SdSidebarMenuControl`
+
+Menu renderer for sidebar. Displays hierarchical menus with router links. Supports accordion and flat layouts.
+
+Selector: `sd-sidebar-menu`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `menus` | `ISdSidebarMenu[]` | Menu items (default: `[]`) |
+| `layout` | `"accordion" \| "flat"` | Root layout mode (auto-selected based on menu count) |
+| `getMenuIsSelectedFn` | `(menu: ISdSidebarMenu) => boolean` | Custom selection check function |
+
+### `ISdSidebarMenu`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Display title |
+| `codeChain` | `string[]` | Code path chain for route generation |
+| `url` | `string` | Optional external URL (opens in new tab) |
+| `icon` | `string` | Optional icon SVG |
+| `children` | `ISdSidebarMenu[]` | Optional child menus |
+
+## `SdSidebarUserControl`
+
+User info section in the sidebar with expandable user menu.
+
+Selector: `sd-sidebar-user`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `userMenu` | `ISidebarUserMenu` | User menu configuration |
+
+### `ISidebarUserMenu`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Menu header title |
+| `menus` | `{ title: string; onClick: () => void }[]` | Menu items |
+
+## `SdTopbarContainerControl`
+
+Layout container for the top navigation bar. Renders as a flex column filling height.
+
+Selector: `sd-topbar-container`
+
+No inputs.
+
+## `SdTopbarControl`
+
+Top navigation bar. Includes optional sidebar toggle button.
+
+Selector: `sd-topbar`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `sidebarContainer` | `SdSidebarContainerControl` | Optional explicit sidebar container reference |
+
+## `SdTopbarMenuControl`
+
+Menu renderer for topbar using dropdown menus. Displays hierarchical menus with router links.
+
+Selector: `sd-topbar-menu`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `menus` | `ISdTopbarMenu[]` | Menu items (default: `[]`) |
+| `getMenuIsSelectedFn` | `(menu: ISdTopbarMenu) => boolean` | Custom selection check function |
+
+### `ISdTopbarMenu`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Display title |
+| `codeChain` | `string[]` | Code path chain for route generation |
+| `url` | `string` | Optional external URL (opens in new tab) |
+| `icon` | `string` | Optional icon SVG |
+| `children` | `ISdTopbarMenu[]` | Optional child menus |
+
+## `SdTopbarUserControl`
+
+User dropdown in topbar. Displays user content as trigger and menu items in dropdown.
+
+Selector: `sd-topbar-user`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `menus` | `ISdTopbarUserMenu[]` (required) | User menu items |
+
+### `ISdTopbarUserMenu`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Menu item title |
+| `onClick` | `() => void` | Click handler |

package/docs/overlay-components.md

@@ -0,0 +1,193 @@
+# Overlay Components
+
+## `SdDropdownControl`
+
+Dropdown trigger container. Opens a popup on click/Enter. Handles positioning and backdrop on mobile.
+
+Selector: `sd-dropdown`
+
+| Input/Model | Type | Description |
+|-------------|------|-------------|
+| `open` (model) | `boolean` | Dropdown open state (default: `false`) |
+| `disabled` | `boolean` (booleanAttribute) | Disabled state (default: `false`) |
+
+## `SdDropdownPopupControl`
+
+Dropdown popup content panel. Positioned fixed relative to the trigger. Handles resize and keyboard navigation.
+
+Selector: `sd-dropdown-popup`
+
+No public inputs. Used as a content child of `SdDropdownControl`.
+
+## `SdModalControl`
+
+Modal dialog component with header, close button, backdrop, resize handles, and drag-to-move support. Created programmatically by `SdModalProvider`.
+
+Selector: `sd-modal`
+
+| Input/Model | Type | Description |
+|-------------|------|-------------|
+| `open` (model) | `boolean` | Open state (default: `false`) |
+| `key` | `string` | Config key for position/size persistence |
+| `title` | `string` | Modal title (default: `""`) |
+| `hideHeader` | `boolean` | Hide header bar (default: `false`) |
+| `hideCloseButton` | `boolean` | Hide close button (default: `false`) |
+| `useCloseByBackdrop` | `boolean` | Close on backdrop click (default: `true`) |
+| `useCloseByEscapeKey` | `boolean` | Close on Escape key (default: `true`) |
+| `float` | `boolean` | Float mode (default: `false`) |
+| `fill` | `boolean` | Fill mode (default: `false`) |
+| `resizable` | `boolean` | Enable resize handles (default: `false`) |
+| `movable` | `boolean` | Enable header drag-to-move (default: `false`) |
+| `position` | `"bottom-right" \| "top-right"` | Position preset |
+| `minHeightPx` | `number` | Minimum height in pixels |
+| `minWidthPx` | `number` | Minimum width in pixels |
+| `heightPx` | `number` | Initial height in pixels |
+| `widthPx` | `number` | Initial width in pixels |
+| `headerStyle` | `string` | Custom header inline style |
+| `noFirstControlFocusing` | `boolean` | Skip auto-focusing first control (default: `false`) |
+| `actionTplRef` | `TemplateRef<any>` | Optional action template for header |
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `closeRequest` | `void` | Emitted when backdrop click, Escape, or close button triggers close |
+
+## `SdPromptModalControl`
+
+Built-in prompt modal. Displays a message and text input. Implements `ISdModal<string>`.
+
+Selector: `sd-prompt-modal`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `message` | `string` (required) | Prompt message text |
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `close` | `string \| undefined` | Emits input value on confirm, undefined on cancel |
+
+## `SdConfirmModalControl`
+
+Built-in confirm modal. Displays a message with confirm/cancel buttons. Implements `ISdModal<boolean>`.
+
+Selector: `sd-confirm-modal`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `message` | `string` (required) | Confirmation message text |
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `close` | `boolean \| undefined` | Emits `true` on confirm, `undefined` on cancel |
+
+## `SdToastControl`
+
+Individual toast notification component. Supports themes, progress bar, and ARIA roles.
+
+Selector: `sd-toast`
+
+| Input/Model | Type | Description |
+|-------------|------|-------------|
+| `open` (model) | `boolean` | Open state with transition (default: `false`) |
+| `useProgress` | `boolean` (booleanAttribute) | Show progress bar (default: `false`) |
+| `theme` | `TSdToastTheme` | Toast theme (default: `"info"`) |
+| `progress` (model) | `number` | Progress percentage 0-100 (default: `0`) |
+| `message` (model) | `string \| undefined` | Toast message text |
+
+## `SdToastContainerControl`
+
+Fixed-position container for toast notifications.
+
+Selector: `sd-toast-container`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `overlap` | `boolean` (booleanAttribute) | Overlap mode (single toast, bottom-left positioned, default: `false`) |
+
+## `SdBusyContainerControl`
+
+Busy/loading overlay container. Shows a loading indicator over its content.
+
+Selector: `sd-busy-container`
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `busy` | `boolean` (booleanAttribute) | Whether to show busy overlay (default: `false`) |
+| `message` | `string \| undefined` | Loading message text |
+| `type` | `TSdBusyType \| undefined` | Indicator type (falls back to `SdBusyProvider.type()`) |
+| `progressPercent` | `number \| undefined` | Optional progress percentage |
+
+### `TSdBusyType`
+
+```typescript
+type TSdBusyType = "spinner" | "bar" | "cube";
+```
+
+## Toast Types
+
+### `TSdToastSeverity`
+
+```typescript
+type TSdToastSeverity = "info" | "success" | "warning" | "danger";
+```
+
+### `TSdToastTheme`
+
+```typescript
+type TSdToastTheme = "primary" | "secondary" | TSdToastSeverity | "gray" | "blue-gray";
+```
+
+### `ISdToast`
+
+Interface for custom toast content components.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `close` | `OutputEmitterRef<O \| undefined>` | Output to emit close result |
+
+### `ISdToastInput`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `Type<T>` | Component type |
+| `inputs` | `Omit<TDirectiveInputSignals<T>, "close">` | Component inputs |
+
+## Modal Types
+
+### `ISdModal`
+
+Interface for modal content components.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `initialized` | `Signal<boolean>` | Whether content is initialized |
+| `close` | `OutputEmitterRef<O \| undefined>` | Output to emit close result |
+| `actionTplRef` | `TemplateRef<any>` | Optional action template for modal header |
+
+### `ISdModalInfo`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Modal title |
+| `type` | `Type<T>` | Component type |
+| `inputs` | `Omit<TDirectiveInputSignals<T>, "initialized" \| "close" \| "actionTplRef">` | Component inputs |
+
+### `ISdModalOptions`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `key` | `string` | Config persistence key |
+| `hideHeader` | `boolean` | Hide header |
+| `hideCloseButton` | `boolean` | Hide close button |
+| `useCloseByBackdrop` | `boolean` | Close on backdrop click |
+| `useCloseByEscapeKey` | `boolean` | Close on Escape |
+| `float` | `boolean` | Float mode |
+| `fill` | `boolean` | Fill mode |
+| `resizable` | `boolean` | Enable resizing |
+| `movable` | `boolean` | Enable moving |
+| `position` | `"bottom-right" \| "top-right"` | Position preset |
+| `minHeightPx` | `number` | Minimum height |
+| `minWidthPx` | `number` | Minimum width |
+| `heightPx` | `number` | Initial height |
+| `widthPx` | `number` | Initial width |
+| `headerStyle` | `string` | Header inline style |
+| `noFirstControlFocusing` | `boolean` | Skip auto-focus |