@simplysm/angular 14.0.8 → 14.0.10

package/docs/ui-layout.md

@@ -0,0 +1,216 @@
+# UI Layout
+
+Layout components for structuring page content: dock panels, panes, views, cards, and kanban boards.
+
+## `SdDockContainerControl`
+
+Flex container that positions child `SdDockControl` panels around a central content area.
+
+```typescript
+@Component({ selector: "sd-dock-container" })
+class SdDockContainerControl {
+  contentClass = input<string>();
+}
+```
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `contentClass` | `string \| undefined` | CSS class applied to the inner content div |
+
+## `SdDockControl`
+
+Dockable panel that attaches to a side of `SdDockContainerControl`. Supports resizing with optional config persistence.
+
+```typescript
+@Component({ selector: "sd-dock" })
+class SdDockControl {
+  key = input<string>();
+  position = input<"top" | "bottom" | "right" | "left">("top");
+  resizable = input(false, { transform: booleanAttribute });
+  size = signal(0);
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `key` | `string \| undefined` | — | Persistence key for resize state |
+| `position` | `"top" \| "bottom" \| "right" \| "left"` | `"top"` | Dock position |
+| `resizable` | `boolean` | `false` | Enable drag-to-resize |
+
+## `SdPaneDirective`
+
+CSS utility directive that makes the host element fill its container with scrollable overflow.
+
+```typescript
+@Directive({ selector: "sd-pane, [sd-pane]" })
+class SdPaneDirective { }
+```
+
+Applies `class="fill"` and `style="display: block"`.
+
+## `SdGapControl`
+
+Empty spacer element with configurable width and/or height.
+
+```typescript
+@Component({ selector: "sd-gap" })
+class SdGapControl {
+  height = input<"xxs" | "xs" | "sm" | "default" | "lg" | "xl" | "xxl">();
+  heightPx = input<number>();
+  width = input<"xxs" | "xs" | "sm" | "default" | "lg" | "xl" | "xxl">();
+  widthPx = input<number>();
+  widthEm = input<number>();
+}
+```
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `height` | size token \| undefined | Named vertical gap |
+| `heightPx` | `number \| undefined` | Explicit height in px |
+| `width` | size token \| undefined | Named horizontal gap |
+| `widthPx` | `number \| undefined` | Explicit width in px |
+| `widthEm` | `number \| undefined` | Explicit width in em |
+
+## `SdViewControl`
+
+Container that shows one child `SdViewItemControl` at a time based on a matched value.
+
+```typescript
+@Component({ selector: "sd-view" })
+class SdViewControl {
+  value = input<any>();
+  fill = input(false, { transform: booleanAttribute });
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `value` | `any` | — | Currently active view value |
+| `fill` | `boolean` | `false` | When true, sets `height: 100%` |
+
+## `SdViewItemControl`
+
+Content panel shown only when its `value` matches the parent `SdViewControl.value`.
+
+```typescript
+@Component({ selector: "sd-view-item" })
+class SdViewItemControl {
+  value = input<any>();
+  isSelected = computed(/* parent.value() === this.value() */);
+}
+```
+
+## `SdCardDirective`
+
+CSS marker directive that applies the `.card` class (background, border-radius, shadow, hover elevation).
+
+```typescript
+@Directive({ selector: "sd-card, [sd-card]" })
+class SdCardDirective { }
+```
+
+## `SdKanbanBoardControl`
+
+Container for kanban lanes. Manages drag-and-drop state and multi-selection.
+
+```typescript
+@Component({ selector: "sd-kanban-board" })
+class SdKanbanBoardControl<L, T> {
+  selectedValues = model<T[]>([]);
+  drop = output<ISdKanbanBoardDropInfo<L, T>>();
+  dragKanban = signal<ISdKanbanDragRef<L, T> | undefined>(undefined);
+}
+```
+
+| Model/Output | Type | Description |
+|--------------|------|-------------|
+| `selectedValues` | `T[]` | Two-way bound selected kanban card values |
+| `drop` | `ISdKanbanBoardDropInfo<L, T>` | Emitted when a card is dropped |
+
+## `ISdKanbanBoardDropInfo`
+
+```typescript
+interface ISdKanbanBoardDropInfo<L, T> {
+  sourceKanbanValue?: T;
+  targetLaneValue?: L;
+  targetKanbanValue?: T;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sourceKanbanValue` | `T \| undefined` | Value of the dragged card |
+| `targetLaneValue` | `L \| undefined` | Value of the target lane |
+| `targetKanbanValue` | `T \| undefined` | Value of the card dropped before |
+
+## `ISdKanbanDragRef`
+
+```typescript
+interface ISdKanbanDragRef<_L, T> {
+  value(): T | undefined;
+  heightOnDrag(): number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `value` | `() => T \| undefined` | Dragged card value |
+| `heightOnDrag` | `() => number` | Card height at drag start (for placeholder) |
+
+## `ISdKanbanDropTarget`
+
+```typescript
+interface ISdKanbanDropTarget<L, T> {
+  targetLaneValue(): L | undefined;
+  targetKanbanValue?(): T | undefined;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `targetLaneValue` | `() => L \| undefined` | Lane value of drop target |
+| `targetKanbanValue` | `(() => T \| undefined) \| undefined` | Card value if dropping before a card |
+
+## `SdKanbanControl`
+
+Individual kanban card. Supports drag-and-drop and shift-click selection. Implements `ISdKanbanDragRef` and `ISdKanbanDropTarget`.
+
+```typescript
+@Component({ selector: "sd-kanban" })
+class SdKanbanControl<L, T> implements ISdKanbanDragRef<L, T>, ISdKanbanDropTarget<L, T> {
+  value = input<T>();
+  selectable = input(false, { transform: booleanAttribute });
+  draggable = input(false, { transform: booleanAttribute });
+  contentClass = input<string>();
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `value` | `T \| undefined` | — | Card identity value |
+| `selectable` | `boolean` | `false` | Enable shift-click selection |
+| `draggable` | `boolean` | `false` | Enable drag-and-drop |
+| `contentClass` | `string \| undefined` | — | CSS class for inner card |
+
+## `SdKanbanLaneControl`
+
+Kanban lane (column) that holds kanban cards. Implements `ISdKanbanDropTarget`. Supports collapse, select-all, and custom title/tool templates.
+
+```typescript
+@Component({ selector: "sd-kanban-lane" })
+class SdKanbanLaneControl<L, T> implements ISdKanbanDropTarget<L, T> {
+  value = input<L>();
+  busy = input(false, { transform: booleanAttribute });
+  useCollapse = input(false, { transform: booleanAttribute });
+  collapse = model(false);
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `value` | `L \| undefined` | — | Lane identity value |
+| `busy` | `boolean` | `false` | Shows busy indicator |
+| `useCollapse` | `boolean` | `false` | Enables collapse toggle |
+| `collapse` | `boolean` | `false` | Two-way collapsed state |
+
+Content templates: `#toolTpl`, `#titleTpl`.

package/docs/ui-navigation.md

@@ -0,0 +1,279 @@
+# UI Navigation
+
+Navigation components: collapse, tabs, pagination, sidebar, and topbar.
+
+## `SdCollapseControl`
+
+Animated collapse/expand container using height-based margin transition.
+
+```typescript
+@Component({ selector: "sd-collapse" })
+class SdCollapseControl {
+  open = input(false, { transform: booleanAttribute });
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `open` | `boolean` | `false` | Whether content is expanded |
+
+## `SdCollapseIconControl`
+
+Animated chevron icon that rotates when the associated collapse is open.
+
+```typescript
+@Component({ selector: "sd-collapse-icon" })
+class SdCollapseIconControl {
+  open = input(false, { transform: booleanAttribute });
+  openRotate = input(90, { transform: numberAttribute });
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `open` | `boolean` | `false` | Rotation active state |
+| `openRotate` | `number` | `90` | Degrees to rotate when open |
+
+## `SdTabControl`
+
+Tab bar container. Manages the selected tab value.
+
+```typescript
+@Component({ selector: "sd-tab" })
+class SdTabControl {
+  value = model<any>();
+}
+```
+
+## `SdTabItemControl`
+
+Individual tab button. Must be a child of `SdTabControl`.
+
+```typescript
+@Component({ selector: "sd-tab-item" })
+class SdTabItemControl {
+  value = input<any>();
+  isSelected = computed(/* parent.value() === this.value() */);
+}
+```
+
+## `SdTabviewControl`
+
+Combined tab bar + content panel container. Builds tabs from projected `SdTabviewItemControl` children.
+
+```typescript
+@Component({ selector: "sd-tabview" })
+class SdTabviewControl<T> {
+  value = model<T | undefined>();
+}
+```
+
+## `SdTabviewItemControl`
+
+Content panel for a single tab within `SdTabviewControl`. Hidden unless selected.
+
+```typescript
+@Component({ selector: "sd-tabview-item" })
+class SdTabviewItemControl<T> {
+  value = input.required<T>();
+  header = input<string>();
+  isSelected = computed(/* parent.value() === this.value() */);
+}
+```
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `value` | `T` | Tab identity value (required) |
+| `header` | `string \| undefined` | Tab bar label (falls back to `value`) |
+
+## `SdPaginationControl`
+
+Pagination bar with first/last/prev-group/next-group navigation.
+
+```typescript
+@Component({ selector: "sd-pagination" })
+class SdPaginationControl {
+  currentPage = model(0);
+  totalPageCount = input(0, { transform: numberAttribute });
+  visiblePageCount = input(10, { transform: numberAttribute });
+
+  hasPrev: Signal<boolean>;
+  hasNext: Signal<boolean>;
+  displayPages: Signal<number[]>;
+
+  goToPage(page: number): void;
+  goToNextGroup(): void;
+  goToPrevGroup(): void;
+  goToFirst(): void;
+  goToLast(): void;
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `currentPage` | `number` | `0` | Zero-based current page (two-way) |
+| `totalPageCount` | `number` | `0` | Total number of pages |
+| `visiblePageCount` | `number` | `10` | Max page buttons per group |
+
+## `SdSidebarContainerControl`
+
+Layout wrapper for sidebar + main content. Manages sidebar toggle state; auto-closes on router `NavigationStart`.
+
+```typescript
+@Component({ selector: "sd-sidebar-container" })
+class SdSidebarContainerControl {
+  toggle: WritableSignal<boolean>;
+}
+```
+
+## `SdSidebarControl`
+
+The sidebar panel. Must be a child of `SdSidebarContainerControl`.
+
+```typescript
+@Component({ selector: "sd-sidebar" })
+class SdSidebarControl {
+  toggle: Signal<boolean>; // mirrors parent
+}
+```
+
+## `SdSidebarMenuControl`
+
+Recursive sidebar navigation menu. Supports accordion and flat layouts, router links, and icons.
+
+```typescript
+@Component({ selector: "sd-sidebar-menu" })
+class SdSidebarMenuControl {
+  menus = input<ISdSidebarMenu[]>([]);
+  layout = input<"accordion" | "flat">();
+  getMenuIsSelectedFn = input<(menu: ISdSidebarMenu) => boolean>();
+}
+```
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `menus` | `ISdSidebarMenu[]` | `[]` | Menu items |
+| `layout` | `"accordion" \| "flat" \| undefined` | auto | Flat when ≤3 root menus |
+| `getMenuIsSelectedFn` | `((menu) => boolean) \| undefined` | — | Custom selection predicate |
+
+## `ISdSidebarMenu`
+
+```typescript
+interface ISdSidebarMenu {
+  title: string;
+  codeChain: string[];
+  url?: string;
+  icon?: string;
+  children?: ISdSidebarMenu[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Display text |
+| `codeChain` | `string[]` | Hierarchical code path for router link |
+| `url` | `string \| undefined` | External URL (opens in new tab) |
+| `icon` | `string \| undefined` | Icon SVG string |
+| `children` | `ISdSidebarMenu[] \| undefined` | Sub-menus |
+
+## `SdSidebarUserControl`
+
+Sidebar user section with a collapsible dropdown menu.
+
+```typescript
+@Component({ selector: "sd-sidebar-user" })
+class SdSidebarUserControl {
+  userMenu = input<ISidebarUserMenu>();
+}
+```
+
+## `ISidebarUserMenu`
+
+```typescript
+interface ISidebarUserMenu {
+  title: string;
+  menus: { title: string; onClick: () => void }[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | User display name |
+| `menus` | `{ title: string; onClick: () => void }[]` | Dropdown action items |
+
+## `SdTopbarContainerControl`
+
+Simple flex column layout shell for topbar + content area.
+
+```typescript
+@Component({ selector: "sd-topbar-container" })
+class SdTopbarContainerControl { }
+```
+
+## `SdTopbarControl`
+
+Top navigation bar. Optionally renders a hamburger button to toggle an associated sidebar.
+
+```typescript
+@Component({ selector: "sd-topbar" })
+class SdTopbarControl {
+  sidebarContainer = input<SdSidebarContainerControl>();
+}
+```
+
+## `SdTopbarMenuControl`
+
+Horizontal topbar navigation menu with dropdown sub-menus.
+
+```typescript
+@Component({ selector: "sd-topbar-menu" })
+class SdTopbarMenuControl {
+  menus = input<ISdTopbarMenu[]>([]);
+  getMenuIsSelectedFn = input<(menu: ISdTopbarMenu) => boolean>();
+}
+```
+
+## `ISdTopbarMenu`
+
+```typescript
+interface ISdTopbarMenu {
+  title: string;
+  codeChain: string[];
+  url?: string;
+  icon?: string;
+  children?: ISdTopbarMenu[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Display text |
+| `codeChain` | `string[]` | Hierarchical code path for router link |
+| `url` | `string \| undefined` | External URL (opens in new tab) |
+| `icon` | `string \| undefined` | Icon SVG string |
+| `children` | `ISdTopbarMenu[] \| undefined` | Sub-menus |
+
+## `SdTopbarUserControl`
+
+Topbar user button with a dropdown menu.
+
+```typescript
+@Component({ selector: "sd-topbar-user" })
+class SdTopbarUserControl {
+  menus = input.required<ISdTopbarUserMenu[]>();
+}
+```
+
+## `ISdTopbarUserMenu`
+
+```typescript
+interface ISdTopbarUserMenu {
+  title: string;
+  onClick: () => void;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Menu item label |
+| `onClick` | `() => void` | Click handler |