@nuraly/runtime 0.1.0

package/components/ui/nuraly-ui/src/components/timeline/README.md

@@ -0,0 +1,340 @@
+# Timeline Component
+
+Vertical display timeline for showing a series of events in chronological order. When a series of information needs to be ordered by time (ascending or descending).
+
+## Installation
+
+```bash
+npm install @nuralyui/timeline
+```
+
+## Usage
+
+### Basic Timeline
+
+```html
+<nr-timeline></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Create a services site', label: '2015-09-01' },
+    { children: 'Solve initial network problems', label: '2015-09-01' },
+    { children: 'Technical testing', label: '2015-09-01' },
+    { children: 'Network problems being solved', label: '2015-09-01' }
+  ];
+</script>
+```
+
+### With Custom Colors
+
+```html
+<nr-timeline></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Create a services site', color: 'green' },
+    { children: 'Solve initial network problems', color: 'blue' },
+    { children: 'Technical testing', color: 'red' },
+    { children: 'Network problems being solved', color: 'gray' }
+  ];
+</script>
+```
+
+### With Custom Icons
+
+```html
+<nr-timeline></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Create a services site', dot: 'clock-circle' },
+    { children: 'Solve initial network problems', dot: 'check-circle' },
+    { children: 'Technical testing', dot: 'close-circle' }
+  ];
+</script>
+```
+
+### Alternate Mode
+
+```html
+<nr-timeline mode="alternate"></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Create a services site', label: '2015-09-01' },
+    { children: 'Solve initial network problems', label: '2015-09-01' },
+    { children: 'Technical testing', label: '2015-09-01' }
+  ];
+</script>
+```
+
+### Right Mode
+
+```html
+<nr-timeline mode="right"></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Create a services site', label: '2015-09-01' },
+    { children: 'Solve initial network problems', label: '2015-09-01' }
+  ];
+</script>
+```
+
+### With Pending State
+
+```html
+<nr-timeline pending="Recording..."></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Create a services site', label: '2015-09-01' },
+    { children: 'Solve initial network problems', label: '2015-09-01' },
+    { children: 'Technical testing', label: '2015-09-01' }
+  ];
+</script>
+```
+
+### With Custom Pending Dot
+
+```html
+<nr-timeline pending="Loading..." pending-dot="loading"></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Step 1 completed' },
+    { children: 'Step 2 completed' },
+    { children: 'Step 3 in progress' }
+  ];
+</script>
+```
+
+### Reverse Order
+
+```html
+<nr-timeline reverse></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'First event', label: '2015-09-01' },
+    { children: 'Second event', label: '2015-09-02' },
+    { children: 'Third event', label: '2015-09-03' }
+  ];
+</script>
+```
+
+### Custom Position in Alternate Mode
+
+```html
+<nr-timeline mode="alternate"></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Left side', position: 'left' },
+    { children: 'Right side', position: 'right' },
+    { children: 'Left side again', position: 'left' }
+  ];
+</script>
+```
+
+## React Usage
+
+```jsx
+import { NrTimeline } from '@nuralyui/timeline/react';
+function App() {
+  const items = [
+    { children: 'Create a services site', label: '2015-09-01' },
+    { children: 'Solve initial network problems', label: '2015-09-01' },
+    { children: 'Technical testing', label: '2015-09-01' }
+  ];
+  return (
+    <>
+      {/* Basic timeline */}
+      <NrTimeline items={items} />
+      {/* Alternate mode */}
+      <NrTimeline mode="alternate" items={items} />
+      {/* With pending */}
+      <NrTimeline items={items} pending="Recording..." />
+      {/* Reverse */}
+      <NrTimeline items={items} reverse />
+    </>
+  );
+}
+```
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `items` | `TimelineItem[]` | `[]` | Array of timeline items |
+| `mode` | `TimelineMode` | `'left'` | Timeline display mode (left, right, alternate) |
+| `pending` | `string` | `undefined` | Pending state content |
+| `pendingDot` | `string` | `undefined` | Custom pending dot icon name |
+| `reverse` | `boolean` | `false` | Reverse timeline order |
+
+### TimelineItem Interface
+
+```typescript
+interface TimelineItem {
+  children: string;              // Item content
+  label?: string;                // Optional label (timestamp, date, etc.)
+  color?: TimelineItemColor | string;  // Dot color (preset or custom)
+  dot?: string;                  // Custom dot icon name
+  position?: TimelineItemPosition;  // Custom position in alternate mode
+  className?: string;            // Custom class name
+}
+```
+
+### TimelineMode Enum
+
+```typescript
+enum TimelineMode {
+  Left = 'left',
+  Right = 'right',
+  Alternate = 'alternate',
+}
+```
+
+### TimelineItemColor Enum
+
+```typescript
+enum TimelineItemColor {
+  Blue = 'blue',
+  Red = 'red',
+  Green = 'green',
+  Gray = 'gray',
+}
+```
+
+### TimelineItemPosition Enum
+
+```typescript
+enum TimelineItemPosition {
+  Left = 'left',
+  Right = 'right',
+}
+```
+
+### CSS Custom Properties
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `--nuraly-timeline-item-padding-bottom` | Bottom padding of timeline item | `20px` |
+| `--nuraly-timeline-tail-width` | Width of connecting line | `2px` |
+| `--nuraly-timeline-tail-color` | Color of connecting line | `rgba(5, 5, 5, 0.06)` |
+| `--nuraly-timeline-dot-bg` | Background color of dot | `#ffffff` |
+| `--nuraly-timeline-dot-border-width` | Border width of dot | `2px` |
+
+## Examples
+
+### Project Timeline
+
+```html
+<nr-timeline></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { 
+      children: 'Project kickoff meeting', 
+      label: '2024-01-01',
+      color: 'green'
+    },
+    { 
+      children: 'Requirements gathering completed', 
+      label: '2024-01-15',
+      color: 'green'
+    },
+    { 
+      children: 'Development phase started', 
+      label: '2024-02-01',
+      color: 'blue'
+    },
+    { 
+      children: 'Testing in progress', 
+      label: '2024-03-01',
+      color: 'blue',
+      dot: 'clock-circle'
+    }
+  ];
+  timeline.pending = 'Launch scheduled';
+</script>
+```
+
+### Status Timeline
+
+```html
+<nr-timeline></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { children: 'Order placed', color: 'green', dot: 'check-circle' },
+    { children: 'Order confirmed', color: 'green', dot: 'check-circle' },
+    { children: 'In transit', color: 'blue', dot: 'clock-circle' },
+    { children: 'Out for delivery', color: 'gray' }
+  ];
+</script>
+```
+
+### Conversation History
+
+```html
+<nr-timeline mode="alternate"></nr-timeline>
+
+<script>
+  const timeline = document.querySelector('nr-timeline');
+  timeline.items = [
+    { 
+      children: 'User sent message', 
+      label: '09:00 AM',
+      position: 'left'
+    },
+    { 
+      children: 'Support replied', 
+      label: '09:05 AM',
+      position: 'right'
+    },
+    { 
+      children: 'User responded', 
+      label: '09:10 AM',
+      position: 'left'
+    },
+    { 
+      children: 'Issue resolved', 
+      label: '09:15 AM',
+      position: 'right',
+      color: 'green'
+    }
+  ];
+</script>
+```
+
+## Accessibility
+
+- Semantic HTML structure with proper list elements
+- Supports keyboard navigation
+- Color is not the only means of conveying information
+- Proper contrast ratios for all color variants
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## License
+
+MIT © Nuraly, Laabidi Aymen

package/components/ui/nuraly-ui/src/components/timeline/index.ts

@@ -0,0 +1 @@
+export * from './timeline.component.js';

package/components/ui/nuraly-ui/src/components/timeline/react.ts

@@ -0,0 +1,9 @@
+import { createComponent } from '@lit-labs/react';
+import * as React from 'react';
+import { NrTimelineElement } from './timeline.component.js';
+export const NrTimeline = createComponent({
+  tagName: 'nr-timeline',
+  elementClass: NrTimelineElement,
+  react: React,
+  events: {},
+});

package/components/ui/nuraly-ui/src/components/timeline/timeline.component.ts

@@ -0,0 +1,235 @@
+/**
+ * @license
+ * Copyright 2023 Nuraly, Laabidi Aymen
+ * SPDX-License-Identifier: MIT
+ */
+
+import { html, LitElement, nothing, TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { classMap } from 'lit/directives/class-map.js';
+import { map } from 'lit/directives/map.js';
+import { styleMap } from 'lit/directives/style-map.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { styles } from './timeline.style.js';
+import { NuralyUIBaseMixin } from '@nuralyui/common/mixins';
+import {
+    TimelineMode,
+    TimelineItem,
+    TimelineItemColor,
+    TimelineItemPosition
+} from './timeline.types.js';
+
+/**
+ * # Timeline Component
+ * 
+ * Vertical display timeline for showing a series of events in chronological order.
+ * 
+ * ## Features
+ * - Multiple display modes (left, right, alternate)
+ * - Custom dot colors and icons
+ * - Label support for timestamps
+ * - Pending state for ongoing activities
+ * - Reverse order option
+ * - Custom positioning in alternate mode
+ * - Theme-aware styling
+ * 
+ * ## Usage
+ * ```html
+ * <!-- Basic timeline -->
+ * <nr-timeline .items="${[
+ *   { children: 'Create a services site', label: '2015-09-01' },
+ *   { children: 'Solve initial network problems', label: '2015-09-01' },
+ *   { children: 'Technical testing', label: '2015-09-01' }
+ * ]}"></nr-timeline>
+ * 
+ * <!-- With custom colors -->
+ * <nr-timeline .items="${[
+ *   { children: 'Success', color: 'green' },
+ *   { children: 'Error', color: 'red' },
+ *   { children: 'Processing', color: 'blue' }
+ * ]}"></nr-timeline>
+ * 
+ * <!-- Alternate mode -->
+ * <nr-timeline mode="alternate" .items="${items}"></nr-timeline>
+ * 
+ * <!-- With pending state -->
+ * <nr-timeline pending="Recording..." .items="${items}"></nr-timeline>
+ * ```
+ * 
+ * @element nr-timeline
+ * 
+ * @cssproperty --nuraly-timeline-item-padding-bottom - Bottom padding of timeline item
+ * @cssproperty --nuraly-timeline-tail-width - Width of connecting line
+ * @cssproperty --nuraly-timeline-tail-color - Color of connecting line
+ * @cssproperty --nuraly-timeline-dot-bg - Background color of dot
+ * @cssproperty --nuraly-timeline-dot-border-width - Border width of dot
+ */
+@customElement('nr-timeline')
+export class NrTimelineElement extends NuralyUIBaseMixin(LitElement) {
+  static override styles = styles;
+
+  override requiredComponents = ['nr-icon'];
+
+  /**
+   * Timeline display mode
+   */
+  @property({ type: String, reflect: true })
+  mode: TimelineMode = TimelineMode.Left;
+
+  /**
+   * Timeline items array
+   */
+  @property({ type: Array })
+  items: TimelineItem[] = [];
+
+  /**
+   * Pending state - shows a pending item at the end
+   */
+  @property({ type: String })
+  pending?: string;
+
+  /**
+   * Custom pending dot icon
+   */
+  @property({ type: String, attribute: 'pending-dot' })
+  pendingDot?: string;
+
+  /**
+   * Reverse timeline order
+   */
+  @property({ type: Boolean, reflect: true })
+  reverse = false;
+
+  /**
+   * Get item position for alternate mode
+   */
+  private getItemPosition(item: TimelineItem, index: number): TimelineItemPosition {
+    if (this.mode !== TimelineMode.Alternate) {
+      return TimelineItemPosition.Left;
+    }
+
+    if (item.position) {
+      return item.position;
+    }
+
+    return index % 2 === 0 ? TimelineItemPosition.Left : TimelineItemPosition.Right;
+  }
+
+  /**
+   * Check if color is a preset color
+   */
+  private isPresetColor(color?: string): boolean {
+    if (!color) return false;
+    const presetColors = ['blue', 'red', 'green', 'gray'];
+    return presetColors.includes(color);
+  }
+
+  /**
+   * Get custom color style for dot
+   */
+  private getCustomColorStyle(color?: string): Record<string, string> {
+    if (!color || this.isPresetColor(color)) {
+      return {};
+    }
+
+    return {
+      borderColor: color,
+    };
+  }
+
+  /**
+   * Render timeline item dot
+   */
+  private renderDot(item: TimelineItem): TemplateResult {
+    const hasCustomDot = !!item.dot;
+    const color = item.color || TimelineItemColor.Blue;
+    const isPreset = this.isPresetColor(color);
+
+    if (hasCustomDot) {
+      return html`
+        <div class="timeline-item-head-custom">
+          <nr-icon name="${ifDefined(item.dot)}"></nr-icon>
+        </div>
+      `;
+    }
+
+    const headClasses = {
+      'timeline-item-head': true,
+      [color]: isPreset,
+    };
+
+    const headStyle = this.getCustomColorStyle(color);
+
+    return html`
+      <div class=${classMap(headClasses)} style=${styleMap(headStyle)}></div>
+    `;
+  }
+
+  /**
+   * Render timeline item
+   */
+  private renderItem(item: TimelineItem, index: number): TemplateResult {
+    const position = this.getItemPosition(item, index);
+    const itemClasses = {
+      'timeline-item': true,
+      'timeline-item-left': position === TimelineItemPosition.Left,
+      'timeline-item-right': position === TimelineItemPosition.Right,
+      [item.className || '']: !!item.className,
+    };
+
+    return html`
+      <li class=${classMap(itemClasses)}>
+        <div class="timeline-item-tail"></div>
+        ${this.renderDot(item)}
+        <div class="timeline-item-content">
+          ${item.label && this.mode === TimelineMode.Alternate
+            ? html`<div class="timeline-item-label">${item.label}</div>`
+            : nothing}
+          <div>${item.children}</div>
+          ${item.label && this.mode !== TimelineMode.Alternate
+            ? html`<div style="color: var(--nuraly-color-text-secondary); margin-top: 4px;">${item.label}</div>`
+            : nothing}
+        </div>
+      </li>
+    `;
+  }
+
+  /**
+   * Render pending item
+   */
+  private renderPendingItem(): TemplateResult {
+    const pendingContent = typeof this.pending === 'string' ? this.pending : 'Loading...';
+    const pendingIconName = this.pendingDot || 'loading';
+
+    return html`
+      <li class="timeline-item pending">
+        <div class="timeline-item-tail"></div>
+        <div class="timeline-item-head-custom">
+          <nr-icon name="${pendingIconName}"></nr-icon>
+        </div>
+        <div class="timeline-item-content">
+          ${pendingContent}
+        </div>
+      </li>
+    `;
+  }
+
+  override render() {
+    if (!this.items || this.items.length === 0) {
+      return nothing;
+    }
+
+    return html`
+      <ul class="timeline">
+        ${map(this.items, (item, index) => this.renderItem(item, index))}
+        ${this.pending ? this.renderPendingItem() : nothing}
+      </ul>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nr-timeline': NrTimelineElement;
+  }
+}