@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/navigation/progress_step_bar/ProgressStepBlock.svelte

@@ -0,0 +1,201 @@
+<script lang="ts">
+    import {ProgressStepStatus} from "./ProgressStep";
+
+    interface Props {
+        status: ProgressStepStatus;
+        pos?: number;
+        topic: string;
+        comment?: string;
+        style?: string;
+        direction: 'vertical' | 'horizontal';
+    }
+
+    let {
+        status,
+        pos = 1,
+        topic,
+        comment = '',
+        style = '',
+        direction
+    }: Props = $props();
+
+
+</script>
+
+<div class="progress-step-block {status} {direction}" {style}>
+    <div class="step-indicator">
+        <div>
+            {#if status === ProgressStepStatus.Completed}
+                <span>✔</span>
+            {:else}
+                <span>{pos}</span>
+            {/if}
+        </div>
+    </div>
+    <div class="step-text {status}">
+        <div class="step-topic" >
+            <span>{topic}</span>
+        </div>
+        {#if comment}
+            <div class="step-comment">
+                <span>{comment}</span>
+            </div>
+        {/if}
+    </div>
+</div>
+
+<style>
+
+    .progress-step-block {
+        flex: 1 1;
+        min-width: 100px;
+        display: flex;
+        flex-direction: row;
+        justify-items: flex-start;
+        color: var(--uniface-progress-step-pending-color, #B3BCCA);
+        margin-left: 8px;
+        background-color: inherit;
+        background: linear-gradient(to bottom, transparent 12px,
+                var(--uniface-progress-step-pending-color, #B3BCCA) 12px,
+                var(--uniface-progress-step-pending-color, #B3BCCA) 14px,
+                transparent 14px);
+    }
+
+    .progress-step-block:first-child {
+        margin-left: 0;
+    }
+
+    .progress-step-block:first-child .step-indicator {
+        margin-left: 0;
+    }
+
+    .step-indicator {
+        flex: 0 0 auto;
+        padding-right: 12px;
+        margin-left: 12px;
+    }
+
+    .step-indicator > div {
+        background-color: var(--uniface-progress-step-bar-color-surface);
+        display: inline-block;
+    }
+
+    .step-indicator span {
+        display: inline-block;
+        text-align: center;
+        width: 24px;
+        height: 24px;
+        line-height: 24px;
+        border-radius: 50%;
+        border: 1px solid var(--uniface-progress-step-pending-color, #B3BCCA);
+        font-size: 1.1em;
+    }
+
+    .progress-step-block.completed {
+        background: linear-gradient(to bottom, transparent 12px,
+                var(--uniface-progress-step-completed-icon-color, #0061FF) 12px,
+                var(--uniface-progress-step-completed-icon-color, #0061FF) 14px,
+                transparent 14px);
+    }
+
+    .progress-step-block.completed .step-indicator span {
+        border: 1px solid var(--uniface-progress-step-completed-icon-color, #0061FF);
+    }
+
+    .step-text {
+        width: 100%;
+        overflow: hidden;
+    }
+
+    .step-topic {
+        width: 100%;
+        background-color: transparent;
+        line-height: 24px;
+        overflow: hidden;
+    }
+
+    .step-topic span {
+        display: inline-block;
+        background-color: var(--uniface-progress-step-bar-color-surface);
+        padding-right: 6px;
+        padding-left: 6px;
+        max-width: 100%;
+        overflow: hidden;
+        white-space: nowrap;
+        text-overflow: ellipsis;
+        vertical-align: top;
+    }
+
+    .progress-step-block:last-child .step-topic {
+        background-color: var(--uniface-progress-step-bar-color-surface);
+    }
+
+    .progress-step-block.processing .step-topic {
+        color: var(--uniface-progress-step-processing-color, #0061FF);
+    }
+
+    .progress-step-block.processing .step-indicator span {
+        background-color: var(--uniface-progress-step-processing-color, #0061FF);
+        color: var(--uniface-progress-step-bar-bg, #ffffff);
+    }
+
+    .progress-step-block.completed .step-topic {
+        color: var(--uniface-progress-step-completed-color, #374151);
+    }
+
+    .progress-step-block.completed .step-indicator span {
+        background-color: var(--uniface-progress-step-completed-icon-bg, #0061FF1A);
+        color: var(--uniface-progress-step-completed-icon-color, #0061FF);
+    }
+
+    .step-comment {
+        line-height: 1.4;
+        font-size: 0.9em;
+    }
+
+    .progress-step-block.completed .step-comment {
+        color: var(--uniface-progress-step-completed-color, #374151);
+    }
+
+    .progress-step-block:last-child {
+        /* Keep the line for the last step */
+    }
+
+    /* Vertical styles */
+    .progress-step-block.vertical {
+        margin-left: 0;
+        background: linear-gradient(to right, transparent 12px, var(--uniface-progress-step-pending-color, #B3BCCA) 14px,
+                var(--uniface-progress-step-pending-color, #B3BCCA) 14px, transparent 13px);
+    }
+
+    .progress-step-block.vertical.completed {
+        background: linear-gradient(to right, transparent 12px, var(--uniface-progress-step-completed-icon-color, #0061FF) 14px,
+                var(--uniface-progress-step-completed-icon-color, #0061FF) 14px, transparent 13px);
+    }
+
+    .progress-step-block.vertical .step-indicator {
+        margin-left: 0;
+    }
+
+    .progress-step-block.vertical .step-indicator > div {
+        background: var(--uniface-progress-step-bar-color-surface);
+        padding: 4px 0;
+    }
+
+    .progress-step-block.vertical:last-child {
+        background: unset;
+    }
+
+    .progress-step-block.vertical .step-topic span {
+        padding-left: 0;
+        display: block;
+    }
+
+    .progress-step-block.vertical:last-child {
+        background: unset;
+    }
+
+    .progress-step-block.vertical:last-child .step-indicator > div {
+        background: transparent;
+    }
+</style>

package/dist/navigation/progress_step_bar/ProgressStepBlock.svelte.d.ts

@@ -0,0 +1,12 @@
+import { ProgressStepStatus } from "./ProgressStep";
+interface Props {
+    status: ProgressStepStatus;
+    pos?: number;
+    topic: string;
+    comment?: string;
+    style?: string;
+    direction: 'vertical' | 'horizontal';
+}
+declare const ProgressStepBlock: import("svelte").Component<Props, {}, "">;
+type ProgressStepBlock = ReturnType<typeof ProgressStepBlock>;
+export default ProgressStepBlock;

package/dist/navigation/progress_step_bar/README.md

@@ -0,0 +1,245 @@
+# ProgressStepBar Component
+
+A multi-step progress indicator showing sequential steps with their completion status. Renders numbered circles connected by a line; each step is `Pending`, `Processing`, or `Completed`. Supports horizontal (default) and vertical layouts. Pure display — no click handlers.
+
+## Features
+
+- **Three statuses per step**: `Pending` (gray number), `Processing` (solid blue circle), `Completed` (blue tinted circle with checkmark)
+- **Connector line**: drawn via CSS `linear-gradient` between adjacent circles; the line color follows step status (blue when completed, gray when pending)
+- **Horizontal or vertical layout**: horizontal default, vertical for sidebars
+- **Optional comment per step**: smaller secondary text under the topic
+- **Theme hook**: `data-theme="{theme}"` on the outer wrapper
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
+```
+
+## Basic Usage
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
+
+  const steps: ProgressStep[] = [
+    { topic: 'Registration', comment: 'Complete your profile',   status: ProgressStepStatus.Completed },
+    { topic: 'Verification', comment: 'Verify your email',        status: ProgressStepStatus.Processing },
+    { topic: 'Setup',        comment: 'Configure preferences',    status: ProgressStepStatus.Pending }
+  ];
+</script>
+
+<ProgressStepBar {steps} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `steps` | `ProgressStep[]` | _(required)_ | Ordered list of steps. Each step's position in the array determines its number (`pos` displayed as `idx + 1`). |
+| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. Horizontal = row of left-to-right steps; vertical = column of top-to-bottom steps. |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper |
+
+## ProgressStep Type
+
+```typescript
+interface ProgressStep {
+  topic: string;              // Step title (required)
+  comment?: string;           // Optional secondary text shown below the topic
+  status: ProgressStepStatus; // Current status
+}
+```
+
+## ProgressStepStatus Enum
+
+```typescript
+enum ProgressStepStatus {
+  Pending    = 'pending',     // Gray number, gray text
+  Processing = 'processing',  // Solid blue circle with white number, blue text
+  Completed  = 'completed',   // Blue-tinted circle with checkmark (✔), dark gray text
+}
+```
+
+The enum value is also the CSS class on each step block (`Pending` → `.pending`, etc.).
+
+## Visual Design
+
+```text
+Horizontal:
+
+   ●─────●─────○─────○
+   1     2     3     4
+   Reg   Ver   Setup Done
+   Done  ...
+
+Vertical:
+
+   ●
+   │ 1
+   │ Registration
+   │
+   ●
+   │ 2
+   │ Verification
+   │
+   ○
+     3
+     Setup
+```
+
+Filled circles (●) are completed or processing; outlined circles (○) are pending. The connecting line is blue when the step is `Completed`, gray when `Pending`.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="uniface-progress-step-container {direction}" data-theme="..." style="...">
+  <div class="container-panel">
+    <!-- per step -->
+    <div class="progress-step-block {status} {direction}">
+      <div class="step-indicator">
+        <div>
+          <span>✔</span>          <!-- Completed -->
+          <!-- OR -->
+          <span>{pos}</span>      <!-- Pending / Processing -->
+        </div>
+      </div>
+      <div class="step-text {status}">
+        <div class="step-topic"><span>{topic}</span></div>
+        <!-- only if comment provided -->
+        <div class="step-comment"><span>{comment}</span></div>
+      </div>
+    </div>
+    ...
+  </div>
+</div>
+```
+
+### CSS Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `--uniface-progress-step-bar-color-surface` | Container background (also used as the "background behind the line" so the line appears to break around the circle) |
+| `--uniface-progress-step-bar-bg` | Foreground inside processing circle (default white) |
+| `--uniface-progress-step-pending-color` | Pending circle border + line + text (gray) |
+| `--uniface-progress-step-completed-color` | Completed topic/comment text (dark gray) |
+| `--uniface-progress-step-completed-icon-color` | Completed circle border + checkmark + line (blue) |
+| `--uniface-progress-step-completed-icon-bg` | Completed circle background (light blue tint) |
+| `--uniface-progress-step-processing-color` | Processing circle fill + topic text (blue) |
+
+### How the connector line works
+
+Each step's `background` is a `linear-gradient` that draws a 2px horizontal (or vertical) line at the indicator's center. The circle itself sits on top with a same-color background, making it look like the line breaks around the circle. Status-specific classes override the gradient color.
+
+This is fragile — if you change `--uniface-progress-step-bar-color-surface` to a non-solid background (image, gradient), the line will visually leak through the circle.
+
+## Examples
+
+### Dynamic Progress (Svelte 5 runes)
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
+
+  let steps = $state<ProgressStep[]>([
+    { topic: 'Initialization', comment: 'Setting up...',  status: ProgressStepStatus.Pending },
+    { topic: 'Data Loading',   comment: 'Fetching data...',status: ProgressStepStatus.Pending },
+    { topic: 'Processing',     comment: 'Analyzing...',    status: ProgressStepStatus.Pending },
+    { topic: 'Completion',     comment: 'Finalizing...',   status: ProgressStepStatus.Pending }
+  ]);
+
+  let currentIdx = 0;
+
+  function advance() {
+    if (currentIdx >= steps.length) return;
+
+    steps[currentIdx].status = ProgressStepStatus.Processing;
+
+    setTimeout(() => {
+      steps[currentIdx].status = ProgressStepStatus.Completed;
+      currentIdx++;
+
+      if (currentIdx < steps.length) {
+        steps[currentIdx].status = ProgressStepStatus.Processing;
+        advance();
+      }
+    }, 1500);
+  }
+
+  advance();
+</script>
+
+<ProgressStepBar {steps} />
+```
+
+### Vertical Layout
+
+```svelte
+<div style="height: 480px;">
+  <ProgressStepBar {steps} direction="vertical" />
+</div>
+```
+
+Vertical mode fills the parent's height — make sure the parent has a height or the layout collapses.
+
+### Pure Display (Static Steps)
+
+For a "your order is at step N" type view:
+
+```svelte
+<script lang="ts">
+  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from '@ticatec/uniface-element/ProgressStepBar';
+
+  const orderSteps: ProgressStep[] = [
+    { topic: 'Order Placed',    status: ProgressStepStatus.Completed },
+    { topic: 'Payment Cleared', status: ProgressStepStatus.Completed },
+    { topic: 'Shipped',         status: ProgressStepStatus.Processing },
+    { topic: 'Out for Delivery',status: ProgressStepStatus.Pending },
+    { topic: 'Delivered',       status: ProgressStepStatus.Pending }
+  ];
+</script>
+
+<ProgressStepBar steps={orderSteps} />
+```
+
+## Behavior Notes
+
+- **Pure display.** No click handlers — users can't jump between steps. Pair with [Navigator](../navigator/README.md) if you need interactive step navigation.
+- **Reactive.** Mutate `steps[i].status` (with `$state` array) and the UI updates. The component re-renders via Svelte 5 reactivity.
+- **`topic` truncates with `…`** (`white-space: nowrap; text-overflow: ellipsis`). Keep topics short.
+- **`comment` is multi-line** but doesn't have its own truncation — long comments can break the layout.
+- **First step has no left margin**; subsequent steps use `margin-left: 8px` (horizontal) or no margin (vertical, since the line connects vertically).
+- **Last step keeps the line** for visual continuity — there's a `.progress-step-block:last-child` rule but it's empty in horizontal mode. In vertical mode, the line is unset on the last step.
+
+## Accessibility
+
+- **Purely visual.** No ARIA roles, no `aria-current` for the processing step, no `aria-label` on the indicators.
+- The checkmark `✔` is literal Unicode text — screen readers will read "check mark". Consider replacing with an icon font + `aria-hidden="true"` in a fork if it's noisy.
+- Step status (Pending / Processing / Completed) is conveyed by color + circle fill alone — no text alternative. Add `aria-label="Step N: {topic}, {status}"` on each block in a fork for screen-reader support.
+- No keyboard interaction (purely display, so this is fine).
+
+## Known Quirks
+
+1. **The connector line is implemented via `background` gradient** on each step block. If you change the surface color (`--uniface-progress-step-bar-color-surface`) to a non-solid background, the line will leak through the circles.
+
+## Best Practices
+
+1. **Use `$state` for the `steps` array** if you want live progress updates. Mutating `steps[i].status` re-renders.
+2. **Keep `topic` short** — it truncates with `…`. Move detail to `comment`.
+3. **Use `direction="vertical"` only inside a height-constrained parent** (sidebar, drawer). Otherwise it collapses.
+4. **One `Processing` step at a time** — having multiple gives a confusing visual. Mark earlier steps `Completed`.
+5. **Override colors via CSS variables**, not by styling the inner classes — the structure is fragile (see connector line note).
+6. **For interactive step nav, use [Navigator](../navigator/README.md)** instead — this component is display-only.
+
+## Related Components
+
+- [Navigator](../navigator/README.md) — interactive step navigation (clickable items)
+- [ProgressSteps](../progress_steps/README.md) — sibling step component (if present)