@adarsh.nishad/activityual-ui 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+# @adarsh.nishad/activityual-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A modern, accessible, high-performance Web Component library for the **Activityual** personal habit rhythm and quantified-self application, built with [Lit](https://lit.dev/).
+
+---
+
+## 🎨 Design System
+
+`activityual-ui` is crafted based on the **Vaulto Obsidian** design system:
+- **Primary Color:** Vaulto Signature Orange (`#FF4305` / `#E93B00`) with ambient neon glow
+- **Secondary / Success Color:** Financial Positive Emerald (`#25D366` / `rgba(37, 211, 102, 0.12)`)
+- **Negative / Missed Color:** Crimson Red (`#FF3434` / `rgba(255, 52, 52, 0.12)`)
+- **Pending / Neutral Color:** Amber (`#F59E0B`) & Slate (`#A5A5A5`)
+- **Backgrounds & Surfaces:** Tiered charcoal foundation (`#080808`, `#1B1B1B`, `#202020`, `#272727`)
+- **Glassmorphism & Depth:** Translucent cards with 20px–28px backdrop blur and low-chrome ambient borders
+- **Typography:** Sans-serif interface (`Inter`, `'SF Pro Display'`) & telemetry numbers (`'JetBrains Mono'`)
+
+---
+
+## 📦 Components
+
+| Component | Description | Docs |
+| :--- | :--- | :--- |
+| **`activityual-button`** | Interactive pill button (`primary`, `secondary`, `amber`, `charcoal`, `ghost`, `danger`) with loading spinner | [Docs](docs/button.md) |
+| **`activityual-card`** | Obsidian glass container card (`default`, `amber`, `inset`, `shell`) with customizable padding | [Docs](docs/card.md) |
+| **`activityual-activity-card`** | Core habit ritual card with category glyph, streak badge, 5-day consistency trail, and interactive action buttons | [Docs](docs/activity-card.md) |
+| **`activityual-stat-card`** | Metrics and KPI display card with delta pill indicators and monospace values | [Docs](docs/stat-card.md) |
+| **`activityual-progress-ring`** | Circular SVG progress ring with animated stroke and automatic emerald completion state | [Docs](docs/progress-ring.md) |
+| **`activityual-streak-badge`** | Visual flame streak badge displaying active day counts with optional glow highlight | [Docs](docs/streak-badge.md) |
+| **`activityual-status-pill`** | Activity occurrence status indicators (`done`, `missed`, `pending`) in `sm` and `md` sizes | [Docs](docs/status-pill.md) |
+| **`activityual-chart-panel`** | Weekly consistency and rhythm bar chart panel mapped against 80% target baseline | [Docs](docs/chart-panel.md) |
+| **`activityual-recommendation-banner`** | AI Coach habit optimization banner displaying suggested execution windows & reasons | [Docs](docs/recommendation-banner.md) |
+| **`activityual-empty-state`** | Dashed-border presentation placeholder for empty habit lists and categories | [Docs](docs/empty-state.md) |
+| **`activityual-confirm-dialog`** | Accessible confirmation modal dialog with 28px backdrop blur and danger mode | [Docs](docs/confirm-dialog.md) |
+| **`activityual-form-field`** | Styled form input wrapper with floating label, validation error feedback, and required star | [Docs](docs/form-field.md) |
+
+---
+
+## 🚀 Getting Started
+
+### Installation
+
+```bash
+npm install @adarsh.nishad/activityual-ui
+```
+
+### Start Dev Server (with Playground Demo)
+
+Run the local interactive design system playground:
+
+```bash
+# Directly from packages/activityual-ui:
+npm start
+
+# Or from repository root:
+npm run start:ui
+```
+
+### Build for Production
+
+Compile all TypeScript elements and type definitions into `dist/`:
+
+```bash
+# Directly in package:
+npm run build
+
+# Or from repository root:
+npm run build:ui
+```
+
+---
+
+## 💻 Usage
+
+### 1. In HTML / Vanilla JavaScript
+
+```html
+<script type="module" src="https://unpkg.com/@adarsh.nishad/activityual-ui"></script>
+
+<!-- Activity Card with Streak Badge & Status -->
+<activityual-activity-card
+  activity-id="act-1"
+  title="Morning Sunlight & Hydration"
+  category="Health"
+  frequency="Daily • 07:30 AM"
+  streak="14"
+  status="done"
+  notes="Drink 500ml water and get 15 min direct sunlight"
+></activityual-activity-card>
+
+<!-- Circular Progress Ring -->
+<activityual-progress-ring percentage="85" label="Weekly Flow" size="130"></activityual-progress-ring>
+```
+
+### 2. In SvelteKit / Web Applications (`apps/web`)
+
+In `src/routes/+layout.svelte` or your application entry point:
+
+```typescript
+import '@adarsh.nishad/activityual-ui';
+```
+
+Then use the custom elements directly in any `.svelte` file:
+
+```svelte
+<activityual-stat-card
+  title="Completion Rhythm"
+  value="88.4%"
+  subtitle="vs 82.0% baseline"
+  delta="+6.4%"
+  delta-type="positive"
+></activityual-stat-card>
+
+<activityual-button
+  variant="primary"
+  size="md"
+  onclick={() => console.log('Action triggered')}
+>
+  Record Completion
+</activityual-button>
+```
+
+### 3. Individual Subpath Imports (Tree-Shaking)
+
+Import individual custom elements without loading the entire bundle:
+
+```typescript
+import '@adarsh.nishad/activityual-ui/button';
+import '@adarsh.nishad/activityual-ui/activity-card';
+import '@adarsh.nishad/activityual-ui/progress-ring';
+import '@adarsh.nishad/activityual-ui/stat-card';
+```
+
+### 4. Design Tokens Direct Access
+
+Import the typed Vaulto Obsidian token dictionary directly in JavaScript / TypeScript:
+
+```typescript
+import { tokens } from '@adarsh.nishad/activityual-ui';
+
+console.log(tokens.colors.primary); // #FF4305
+console.log(tokens.colors.canvasBase); // #080808
+```
+
+---
+
+## 📦 Building & Publishing to npm
+
+Follow these steps whenever you make changes to `packages/activityual-ui` and want to publish a new release:
+
+### Step 1: Verify npm Authentication
+
+```bash
+npm whoami
+```
+
+If not logged in, run:
+
+```bash
+npm login
+```
+
+### Step 2: Build the Library
+
+Compile all custom elements and TypeScript type definitions into `dist/`:
+
+```bash
+# From repository root:
+npm run build:ui
+
+# Or directly in this directory:
+npm run build
+```
+
+### Step 3: Bump Version
+
+Bump the semantic version (`patch`, `minor`, or `major`):
+
+```bash
+# From repository root:
+npm run version:ui:patch   # e.g. 0.1.0 -> 0.1.1
+# or
+npm run version:ui:minor   # e.g. 0.1.0 -> 0.2.0
+# or
+npm run version:ui:major   # e.g. 0.1.0 -> 1.0.0
+
+# Or navigate directly:
+cd packages/activityual-ui
+npm version patch # or minor / major
+```
+
+### Step 4: Publish to npm
+
+Since it is a scoped package (`@adarsh.nishad/...`), publish with public access:
+
+```bash
+# From repository root:
+npm run publish:ui
+
+# Or navigate directly:
+cd packages/activityual-ui
+npm publish --access public
+```
+
+---
+
+## 🛠️ Development
+
+- **Tag Convention:** All custom elements must use the `activityual-` tag prefix (e.g. `activityual-button`, `activityual-activity-card`).
+- **Design Tokens:** Keep design tokens synced with `src/tokens.ts` and `src/tokens.json`.
+- **Type Checking:** Run `npm run check` before committing changes.

package/dist/activity-card.d.ts

@@ -0,0 +1,43 @@
+import { LitElement } from 'lit';
+import './status-pill.js';
+import './button.js';
+export declare class ActivityualActivityCard extends LitElement {
+    static properties: {
+        activityId: {
+            type: StringConstructor;
+        };
+        title: {
+            type: StringConstructor;
+        };
+        category: {
+            type: StringConstructor;
+        };
+        frequency: {
+            type: StringConstructor;
+        };
+        status: {
+            type: StringConstructor;
+        };
+        streak: {
+            type: NumberConstructor;
+        };
+        notes: {
+            type: StringConstructor;
+        };
+        readOnly: {
+            type: BooleanConstructor;
+        };
+    };
+    activityId: string;
+    title: string;
+    category: string;
+    frequency: string;
+    status: 'done' | 'missed' | 'pending';
+    streak: number;
+    notes: string;
+    readOnly: boolean;
+    static styles: import("lit").CSSResult;
+    getCategoryIcon(cat: string): string;
+    handleAction(status: 'done' | 'missed'): void;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/activity-card.js

@@ -0,0 +1,302 @@
+import { LitElement, html, css } from 'lit';
+import './status-pill.js';
+import './button.js';
+export class ActivityualActivityCard extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.activityId = '';
+        this.title = '';
+        this.category = 'General';
+        this.frequency = 'Daily';
+        this.status = 'pending';
+        this.streak = 0;
+        this.notes = '';
+        this.readOnly = false;
+    }
+    static { this.properties = {
+        activityId: { type: String },
+        title: { type: String },
+        category: { type: String },
+        frequency: { type: String },
+        status: { type: String },
+        streak: { type: Number },
+        notes: { type: String },
+        readOnly: { type: Boolean }
+    }; }
+    static { this.styles = css `
+		:host {
+			display: block;
+			box-sizing: border-box;
+		}
+
+		.card {
+			background: linear-gradient(145deg, rgba(42, 42, 42, 0.65) 0%, rgba(24, 24, 24, 0.8) 100%);
+			backdrop-filter: blur(20px);
+			-webkit-backdrop-filter: blur(20px);
+			border: 1px solid rgba(255, 255, 255, 0.05);
+			border-radius: 14px;
+			padding: 1rem 1.25rem;
+			box-shadow:
+				0 8px 24px -4px rgba(0, 0, 0, 0.45),
+				inset 0 1px 0 rgba(255, 255, 255, 0.08);
+			font-family: Inter, 'SF Pro Display', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+			display: flex;
+			align-items: center;
+			justify-content: space-between;
+			gap: 1rem;
+			transition: all 0.25s cubic-bezier(0.16, 1, 0.3, 1);
+			box-sizing: border-box;
+		}
+
+		.card:hover {
+			background: linear-gradient(145deg, rgba(48, 48, 48, 0.75) 0%, rgba(28, 28, 28, 0.88) 100%);
+			transform: translateY(-1px);
+			border-color: rgba(255, 255, 255, 0.1);
+			box-shadow:
+				0 14px 32px -6px rgba(0, 0, 0, 0.55),
+				inset 0 1px 0 rgba(255, 255, 255, 0.12);
+		}
+
+		.left-cluster {
+			display: flex;
+			align-items: center;
+			gap: 0.85rem;
+			min-width: 0;
+			flex: 1;
+		}
+
+		.category-icon {
+			width: 38px;
+			height: 38px;
+			border-radius: 10px;
+			background: rgba(255, 67, 5, 0.1);
+			border: 1px solid rgba(255, 67, 5, 0.2);
+			color: #ff4305;
+			display: flex;
+			align-items: center;
+			justify-content: center;
+			font-size: 16px;
+			flex-shrink: 0;
+			box-shadow: 0 0 10px rgba(255, 67, 5, 0.15);
+		}
+
+		.info {
+			display: flex;
+			flex-direction: column;
+			gap: 0.2rem;
+			min-width: 0;
+		}
+
+		.title-row {
+			display: flex;
+			align-items: center;
+			gap: 0.5rem;
+			flex-wrap: wrap;
+		}
+
+		.title {
+			font-size: 13.5px;
+			font-weight: 600;
+			color: #f5f5f5;
+			margin: 0;
+			white-space: nowrap;
+			overflow: hidden;
+			text-overflow: ellipsis;
+			letter-spacing: -0.01em;
+		}
+
+		.meta {
+			display: flex;
+			align-items: center;
+			gap: 0.55rem;
+			font-size: 11px;
+			color: #a5a5a5;
+			font-family: 'JetBrains Mono', monospace;
+		}
+
+		.meta-tag {
+			display: inline-flex;
+			align-items: center;
+			gap: 0.25rem;
+		}
+
+		.streak-tag {
+			color: #ff4305;
+			font-weight: 600;
+		}
+
+		.notes {
+			font-size: 11.5px;
+			color: #707070;
+			margin: 0.2rem 0 0 0;
+			display: -webkit-box;
+			-webkit-line-clamp: 1;
+			-webkit-box-orient: vertical;
+			overflow: hidden;
+		}
+
+		.dot-trail {
+			display: flex;
+			align-items: center;
+			gap: 4px;
+			margin-top: 4px;
+		}
+
+		.dot {
+			width: 6px;
+			height: 6px;
+			border-radius: 50%;
+			background: rgba(255, 255, 255, 0.12);
+		}
+
+		.dot.done {
+			background: #25d366;
+			box-shadow: 0 0 6px rgba(37, 211, 102, 0.4);
+		}
+
+		.dot.missed {
+			background: #ff3434;
+			box-shadow: 0 0 6px rgba(255, 52, 52, 0.4);
+		}
+
+		.right-cluster {
+			display: flex;
+			align-items: center;
+			gap: 0.65rem;
+			flex-shrink: 0;
+		}
+
+		.action-btn {
+			width: 32px;
+			height: 32px;
+			border-radius: 9999px;
+			border: 1px solid rgba(255, 255, 255, 0.08);
+			background: rgba(255, 255, 255, 0.04);
+			display: flex;
+			align-items: center;
+			justify-content: center;
+			cursor: pointer;
+			font-size: 13px;
+			font-weight: 700;
+			color: #a5a5a5;
+			transition: all 0.2s cubic-bezier(0.16, 1, 0.3, 1);
+			outline: none;
+		}
+
+		.action-btn:focus-visible {
+			box-shadow: 0 0 0 2px rgba(255, 67, 5, 0.4);
+		}
+
+		.action-done:hover {
+			background: rgba(37, 211, 102, 0.2);
+			border-color: #25d366;
+			color: #25d366;
+			box-shadow: 0 0 10px rgba(37, 211, 102, 0.3);
+			transform: scale(1.05);
+		}
+
+		.action-done.active {
+			background: #25d366;
+			border-color: #25d366;
+			color: #ffffff;
+			box-shadow: 0 0 12px rgba(37, 211, 102, 0.4);
+		}
+
+		.action-missed:hover {
+			background: rgba(255, 52, 52, 0.2);
+			border-color: #ff3434;
+			color: #ff3434;
+			box-shadow: 0 0 10px rgba(255, 52, 52, 0.3);
+			transform: scale(1.05);
+		}
+
+		.action-missed.active {
+			background: #ff3434;
+			border-color: #ff3434;
+			color: #ffffff;
+			box-shadow: 0 0 12px rgba(255, 52, 52, 0.4);
+		}
+	`; }
+    getCategoryIcon(cat) {
+        const lower = cat.toLowerCase();
+        if (lower.includes('health') || lower.includes('hydration') || lower.includes('water'))
+            return '💧';
+        if (lower.includes('fit') || lower.includes('workout') || lower.includes('sport'))
+            return '⚡';
+        if (lower.includes('mind') || lower.includes('read') || lower.includes('meditat'))
+            return '📖';
+        if (lower.includes('code') || lower.includes('deep') || lower.includes('work'))
+            return '🎯';
+        return '✨';
+    }
+    handleAction(status) {
+        this.dispatchEvent(new CustomEvent('status-change', {
+            detail: { activityId: this.activityId, status },
+            bubbles: true,
+            composed: true
+        }));
+    }
+    render() {
+        return html `
+			<div class="card">
+				<div class="left-cluster">
+					<div class="category-icon" aria-hidden="true">
+						${this.getCategoryIcon(this.category)}
+					</div>
+					<div class="info">
+						<div class="title-row">
+							<h3 class="title">${this.title}</h3>
+						</div>
+						<div class="meta">
+							<span class="meta-tag">${this.category}</span>
+							<span>•</span>
+							<span class="meta-tag">${this.frequency}</span>
+							${this.streak > 0
+            ? html `
+										<span>•</span>
+										<span class="meta-tag streak-tag">🔥 ${this.streak}d streak</span>
+								  `
+            : ''}
+						</div>
+						${this.notes ? html `<p class="notes">${this.notes}</p>` : ''}
+						<div class="dot-trail" aria-label="Recent consistency">
+							<span class="dot done"></span>
+							<span class="dot done"></span>
+							<span class="dot done"></span>
+							<span class="dot done"></span>
+							<span class="dot ${this.status === 'done' ? 'done' : this.status === 'missed' ? 'missed' : ''}"></span>
+						</div>
+					</div>
+				</div>
+
+				<div class="right-cluster">
+					<activityual-status-pill .status="${this.status}" size="sm"></activityual-status-pill>
+
+					${!this.readOnly
+            ? html `
+								<button
+									class="action-btn action-done ${this.status === 'done' ? 'active' : ''}"
+									title="Mark Done"
+									aria-label="Mark ${this.title} Done"
+									@click="${() => this.handleAction('done')}"
+								>
+									✓
+								</button>
+								<button
+									class="action-btn action-missed ${this.status === 'missed' ? 'active' : ''}"
+									title="Mark Missed"
+									aria-label="Mark ${this.title} Missed"
+									@click="${() => this.handleAction('missed')}"
+								>
+									✕
+								</button>
+						  `
+            : ''}
+				</div>
+			</div>
+		`;
+    }
+}
+if (!customElements.get('activityual-activity-card')) {
+    customElements.define('activityual-activity-card', ActivityualActivityCard);
+}

package/dist/button.d.ts

@@ -0,0 +1,32 @@
+import { LitElement } from 'lit';
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger' | 'charcoal' | 'amber';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+export declare class ActivityualButton extends LitElement {
+    static properties: {
+        variant: {
+            type: StringConstructor;
+        };
+        size: {
+            type: StringConstructor;
+        };
+        disabled: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        loading: {
+            type: BooleanConstructor;
+            reflect: boolean;
+        };
+        type: {
+            type: StringConstructor;
+        };
+    };
+    variant: ButtonVariant;
+    size: ButtonSize;
+    disabled: boolean;
+    loading: boolean;
+    type: string;
+    static styles: import("lit").CSSResult;
+    handleClick(e: MouseEvent): void;
+    render(): import("lit-html").TemplateResult<1>;
+}