@nexa-stack/framework 1.0.0 → 1.1.0

package/ui/types/components/art.d.ts

@@ -0,0 +1,11 @@
+/** SVG fallback only — default header uses /nexa-mark.png */
+export declare function renderBrandMark(): string;
+/**
+ * Hero sculpture — asset flush to screen edge
+ * DOM: bloom → media → dots (on top)
+ */
+export declare function renderHeroSculpture(): string;
+/** Product card — mark thumb فقط (مربّع، بدون hero-art) */
+export declare function renderProductMark(): string;
+/** Card media — cover / promo / video (sculpture + bloom + dots) */
+export declare function renderCardHeroArt(variant?: 'cover' | 'product' | 'inline'): string;

package/ui/types/components/card-layouts.d.ts

@@ -0,0 +1,11 @@
+export declare const CARD_LAYOUTS: readonly ["cover", "product", "video", "event", "promo", "pricing", "analytics", "quote", "tasks", "profile", "feature", "media", "icon", "metric"];
+export type CardLayout = (typeof CARD_LAYOUTS)[number] | 'default';
+export declare function has(mods: string[], value: string): boolean;
+export declare function resolveCardLayout(modifiers: string[]): CardLayout;
+export declare function renderCardLayout(element: HTMLElement, layout: CardLayout, defaults: {
+    badge: string;
+    title: string;
+    text: string;
+    cta?: string;
+    tag: string;
+}): string;

package/ui/types/components/card.d.ts

@@ -0,0 +1,11 @@
+/** Card — شكل (layout) + أنيمiشن (model) */
+import { resolveCardLayout, CARD_LAYOUTS } from './card-layouts';
+export declare const CARD_MODELS: readonly ["soft", "fade", "slide", "lift", "tilt", "flip", "magnetic", "float", "glow", "shine", "aurora", "bounce", "zoom", "pulse", "reveal"];
+export { CARD_LAYOUTS };
+export type CardModel = (typeof CARD_MODELS)[number];
+export type CardHover = 'none' | 'soft' | 'lift' | 'glow' | 'flip' | 'tilt' | 'magnetic';
+export declare const CARD_STYLES: readonly ["plain", "bordered", "elevated", "glass", "horizontal", "square", "interactive"];
+export declare function resolveCardModel(modifiers: string[]): CardModel;
+export { resolveCardLayout };
+export declare function prepareCardHost(element: HTMLElement, modifiers: string[]): void;
+export declare function renderCardContent(element: HTMLElement, content: string, modifiers?: string[]): string;

package/ui/types/components/charts.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentRegistry } from '../core/registry';
+export type ChartPoint = {
+    label: string;
+    value: number;
+};
+export declare function parseChartData(raw: string | null): ChartPoint[];
+export declare function registerChartComponents(registry: ComponentRegistry): void;

package/ui/types/components/extra.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentRegistry } from '../core/registry';
+export declare function registerExtraComponents(registry: ComponentRegistry): void;

package/ui/types/components/helpers.d.ts

@@ -0,0 +1,18 @@
+export declare const has: (mods: string[], value: string) => boolean;
+export declare function splitList(raw: string | null, sep?: RegExp | string): string[];
+export declare function formatTitle(raw: string): string;
+export declare function parsePairs(raw: string | null, sep?: string): {
+    head: string;
+    body: string;
+}[];
+export type PlanRow = {
+    name: string;
+    price: string;
+    desc: string;
+    features: string[];
+    cta: string;
+    popular?: boolean;
+};
+export declare function parsePlans(element: HTMLElement): PlanRow[];
+export declare function parseFeatureCards(element: HTMLElement, count: number): string[][];
+export declare function navLinks(element: HTMLElement, fallback: string[]): string;

package/ui/types/components/icons.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Nexa Icons — Lucide (MIT)
+ * أمر: nexa="ico zap" · icon="zap" على الكروت
+ * ستايل: stroke مليان (افتراضي) · fill / solid · thin
+ */
+import type { IconNode } from 'lucide';
+export type NexaIconName = string;
+export type NexaIconWeight = 'regular' | 'bold' | 'thin' | 'fill';
+declare const SIZE: {
+    readonly sm: 18;
+    readonly md: 24;
+    readonly lg: 32;
+    readonly xl: 40;
+};
+export declare function hasNexaIcon(name: string): boolean;
+export declare function resolveIconNode(name: string): IconNode | null;
+/** كل الأسماء الأساسية (بدون aliases) لصفحة الـ showcase */
+export declare function listNexaIconNames(): string[];
+/** SVG string — يشتغل في render + vitest بدون DOM */
+export declare function renderIcon(name: string, size?: keyof typeof SIZE | number, className?: string, weight?: NexaIconWeight): string;
+/** للكروت: lucide name · emoji · URL */
+export declare function renderCardIcon(raw: string, size?: number, className?: string, weight?: NexaIconWeight): string;
+export declare function registerIconComponent(registry: import('../core/registry').ComponentRegistry): void;
+export {};

package/ui/types/components/index.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentRegistry } from '../core/registry';
+export declare function registerPrototypeComponents(registry: ComponentRegistry): void;

package/ui/types/components/pickers.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentRegistry } from '../core/registry';
+declare function pad(n: number): string;
+export declare function registerPickerComponents(registry: ComponentRegistry): void;
+/** يُستخدم من السلوك لإعادة رسم التقويم */
+export declare function renderCalendarGrid(y: number, m: number, selectedIso: string): string;
+export declare function calendarTitle(y: number, m: number): string;
+export declare function formatDateDisplay(iso: string): string;
+export { pad as pad2 };

package/ui/types/components/structure.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentRegistry } from '../core/registry';
+export declare function registerStructureComponents(registry: ComponentRegistry): void;

package/ui/types/core/behaviors.d.ts

@@ -0,0 +1,2 @@
+/** تفاعلات خفيفة للمكوّنات — tabs, accordion, dropdown, modal */
+export declare function wireBehaviors(root?: ParentNode): void;

package/ui/types/core/brand-assets.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Nexa brand assets — مسارات ثابتة فقط.
+ * أي صورة جديدة من التصميم تُنسخ هنا باسم framework (nexa-*)
+ * ولا تُستخدم أسماء الرفع الخام (Untitled-1.png, nexa.png, …) في الكود.
+ */
+export declare const NEXA_ASSETS: {
+    /** Default mark — 128px, transparent, cropped from source */
+    readonly mark: "/nexa-mark.png";
+    /** High-res master (1536px) — do not use in HTML directly */
+    readonly markSource: "/nexa-mark-source.png";
+    readonly mark512: "/nexa-mark-512.png";
+    readonly mark256: "/nexa-mark-256.png";
+    readonly mark128: "/nexa-mark.png";
+    readonly mark96: "/nexa-mark-96.png";
+    readonly mark64: "/nexa-mark-64.png";
+    readonly mark48: "/nexa-mark-48.png";
+    readonly mark40: "/nexa-mark-40.png";
+    readonly mark32: "/nexa-mark-32.png";
+    readonly mark24: "/nexa-mark-24.png";
+    readonly markApple: "/nexa-mark-apple.png";
+    /** Product card thumb — 384px square, crisp on retina */
+    readonly markProduct: "/nexa-mark-product.png";
+    readonly markProduct256: "/nexa-mark-product-256.png";
+    readonly wordmark: "/nexa-wordmark.png";
+    readonly heroSculpture: "/nexa-hero-sculpture.png";
+    readonly heroSculpture640: "/nexa-hero-sculpture-640.png";
+    readonly heroSculpture960: "/nexa-hero-sculpture-960.png";
+    readonly heroSculpture1280: "/nexa-hero-sculpture-1280.png";
+    readonly visionReference: "/nexa-palette-vision.png";
+    readonly cardsVision: "/nexa-cards-vision.jpg";
+    readonly cardsDir: "/cards/";
+    /** على الكروت: image="hero" أو art="hero" */
+    readonly cardHeroArt: "hero";
+    readonly favicon: "/favicon.svg";
+};
+export declare function resolveBrandAsset(src: string): string;
+export declare function isHeroArtToken(src: string): boolean;
+export type NexaAssetKey = keyof typeof NEXA_ASSETS;
+/** Retina srcset for mark icon */
+export declare function markSrcSet(displayPx?: number): string;
+/** Product card mark — square thumb, fixed column width */
+export declare function productMarkSrcSet(): string;
+/** Card/cover sculpture — pre-sized to avoid browser upscale blur */
+export declare function sculptureCardSrcSet(): string;

package/ui/types/core/colormap.d.ts

@@ -0,0 +1,49 @@
+/** Color Map API — مولّد خريطة ألوان من لون واحد (مثل Sass variables لكن أبسط) */
+export type ColorMapName = 'violet' | 'azure' | 'gold' | 'emerald' | 'coral';
+export type BrandStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+export type BrandScale = Record<BrandStep, string>;
+export declare const colorMapNames: ColorMapName[];
+export declare const brandSteps: BrandStep[];
+/** مرادفات الأوامر → اسم الخريطة */
+export declare const colorAliases: Record<string, ColorMapName>;
+/** أسماء جاهزة → hex — map pink */
+export declare const mapPresets: Record<string, string>;
+export declare const SAVED_MAPS_KEY = "nexa-saved-maps";
+/** يطبّع اسم الخريطة المحفوظة — map:my-brand → my-brand */
+export declare function normalizeMapName(name: string): string;
+/** يقرأ الخرائط المحفوظة من localStorage */
+export declare function getSavedMaps(): Record<string, string>;
+/** يحفظ خريطة باسم — map:my-brand */
+export declare function saveBrandMap(name: string, seed: string): string;
+export declare function deleteSavedMap(name: string): boolean;
+export declare function listSavedMapNames(): string[];
+/** يقرأ map #hex أو map pink أو map:my-brand من modifiers */
+export declare function resolveMapSeed(modifiers: string[]): string | null;
+export declare function normalizeHex(input: string): string | null;
+export declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+export declare function rgbToHex(r: number, g: number, b: number): string;
+export declare function rgbToHsl(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    l: number;
+};
+export declare function hslToHex(h: number, s: number, l: number): string;
+/**
+ * من لون واحد (#hex) → سلم brand كامل 50→900
+ * هاد جوهر مولّد الخريطة: بدل ما تكتب 10 متغيرات Sass، بتدخل لون واحد.
+ */
+export declare function generateBrandScale(seed: string): BrandScale;
+/** يطبّق سلم brand على عنصر — كل المكوّنات تقرأ من --nexa-brand-* */
+export declare function applyBrandScale(target: HTMLElement, scale: BrandScale): BrandScale;
+/** يولّد من لون واحد ويطبّق مباشرة */
+export declare function applyBrandColor(target: HTMLElement, seed: string): BrandScale;
+/** يصدّر CSS جاهز للنسخ — تحطه مرة واحدة وكل Nexa يتبع */
+export declare function exportBrandScaleCss(scale: BrandScale, selector?: string): string;
+/** يوزّع لوحة جاهزة على العنصر عبر CSS variables */
+export declare function applyColorMap(target: HTMLElement, name: ColorMapName | string): boolean;
+/** بذرة hue — اختصار سريع لما ما عندك hex جاهز */
+export declare function applyColorSeed(target: HTMLElement, hue: number, chroma?: number): boolean;

package/ui/types/core/echarts-mount.d.ts

@@ -0,0 +1,5 @@
+import * as echarts from 'echarts/core';
+import { buildNexaChartOption, NEXA_ECHARTS_THEME } from './echarts-nexa';
+export declare function mountNexaChart(host: HTMLElement): echarts.ECharts | null;
+export declare function wireEcharts(root?: ParentNode): void;
+export { echarts, NEXA_ECHARTS_THEME, buildNexaChartOption };

package/ui/types/core/echarts-nexa.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Nexa × ECharts — ثيم + بناء options (Apache 2.0)
+ * تخصيص كامل عبر NEXA_ECHARTS_THEME و buildNexaChartOption
+ */
+import type { EChartsOption } from 'echarts';
+import type { ChartPoint } from '../components/charts';
+export declare const NEXA_ECHARTS_THEME: {
+    readonly color: readonly ["#00C6FF", "#2E9EFF", "#2563EB", "#7C5CFC", "#a78bfa", "#38bdf8"];
+    readonly backgroundColor: "transparent";
+    readonly textStyle: {
+        readonly fontFamily: "Inter,Segoe UI,system-ui,sans-serif";
+        readonly color: "#5B6478";
+    };
+    readonly title: {
+        readonly textStyle: {
+            readonly color: "#0B1220";
+            readonly fontWeight: 700;
+        };
+    };
+    readonly legend: {
+        readonly textStyle: {
+            readonly color: "#5B6478";
+        };
+    };
+    readonly grid: {
+        readonly left: 12;
+        readonly right: 12;
+        readonly top: 48;
+        readonly bottom: 28;
+        readonly containLabel: true;
+    };
+    readonly categoryAxis: {
+        readonly axisLine: {
+            readonly lineStyle: {
+                readonly color: "rgba(11,18,32,.08)";
+            };
+        };
+        readonly axisTick: {
+            readonly show: false;
+        };
+        readonly axisLabel: {
+            readonly color: "#5B6478";
+            readonly fontSize: 11;
+        };
+        readonly splitLine: {
+            readonly lineStyle: {
+                readonly color: "rgba(11,18,32,.06)";
+            };
+        };
+    };
+    readonly valueAxis: {
+        readonly axisLine: {
+            readonly show: false;
+        };
+        readonly axisTick: {
+            readonly show: false;
+        };
+        readonly axisLabel: {
+            readonly color: "#5B6478";
+            readonly fontSize: 11;
+        };
+        readonly splitLine: {
+            readonly lineStyle: {
+                readonly color: "rgba(11,18,32,.06)";
+            };
+        };
+    };
+};
+export type NexaChartKind = 'bar' | 'line' | 'area' | 'donut' | 'pie' | 'spark';
+export declare function buildNexaChartOption(kind: NexaChartKind, points: ChartPoint[], animate?: boolean): EChartsOption;
+export declare function parseChartKind(raw: string | null): NexaChartKind;

package/ui/types/core/parser.d.ts

@@ -0,0 +1,11 @@
+export type NexaCommand = {
+    component: string;
+    modifiers: string[];
+    attributes: Record<string, string>;
+    raw: string;
+    label?: string;
+};
+export declare function isHexToken(token: string): boolean;
+export declare function resolveAlias(name: string): string;
+export declare function parseNexa(input: string): NexaCommand;
+export declare function parseNexaPage(input: string): NexaCommand[];

package/ui/types/core/registry.d.ts

@@ -0,0 +1,13 @@
+import type { NexaCommand } from './parser';
+export type NexaRenderContext = NexaCommand & {
+    content: string;
+    element: HTMLElement;
+};
+export type NexaComponent = (context: NexaRenderContext) => string;
+export declare class ComponentRegistry {
+    private components;
+    register(name: string, component: NexaComponent): this;
+    resolve(name: string): NexaComponent | undefined;
+    list(): string[];
+}
+export declare const registry: ComponentRegistry;

package/ui/types/core/renderer.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentRegistry } from './registry';
+export type RenderResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function createNexa({ registry }: {
+    registry: ComponentRegistry;
+}): {
+    render(element: HTMLElement): RenderResult;
+    renderPage(commands: string, target: HTMLElement): RenderResult;
+    mount(root?: Element | Document): RenderResult;
+};

package/ui/types/core/schema.d.ts

@@ -0,0 +1,8 @@
+export type ComponentSchema = {
+    variants?: string[];
+    sizes?: string[];
+    states?: string[];
+    layout?: string[];
+};
+export declare const componentSchemas: Record<string, ComponentSchema>;
+export declare function getComponentSchema(name: string): ComponentSchema;

package/ui/types/core/toast.d.ts

@@ -0,0 +1,11 @@
+export type ToastTone = 'success' | 'warning' | 'danger' | 'info';
+export type ToastOptions = {
+    text: string;
+    tone?: ToastTone;
+    duration?: number;
+};
+/** Shared toast markup — static demo + nexa.toast() API */
+export declare function toastInnerHtml(text: string, tone?: ToastTone): string;
+/** Toast queue — multiple at once via nexa.toast() */
+export declare function pushToast(opts: ToastOptions | string): HTMLDivElement;
+export declare function clearToasts(): void;

package/ui/types/core/validate.d.ts

@@ -0,0 +1 @@
+export declare function validateModifiers(component: string, modifiers: string[]): string | null;

package/ui/types/index.d.ts

@@ -0,0 +1,50 @@
+import { createNexa } from './core/renderer';
+import { registry } from './core/registry';
+import { registerPrototypeComponents } from './components';
+import { applyColorMap, applyColorSeed, colorMapNames, generateBrandScale, applyBrandScale, applyBrandColor, exportBrandScaleCss, normalizeHex, mapPresets, resolveMapSeed, saveBrandMap, deleteSavedMap, listSavedMapNames, getSavedMaps, normalizeMapName } from './core/colormap';
+import './styles/tokens.css';
+import './styles/base.css';
+import './styles/components.css';
+import './styles/presets.css';
+import './styles/primitives.css';
+import './styles/card.css';
+import './styles/card-layouts.css';
+import './styles/icons.css';
+import './styles/controls.css';
+import './styles/forms.css';
+import './styles/dropdown.css';
+import './styles/sections.css';
+import './styles/capabilities.css';
+import './styles/widgets.css';
+import './styles/essential.css';
+import './styles/brand.css';
+import './styles/charts.css';
+import './styles/vision.css';
+import { pushToast, clearToasts } from './core/toast';
+import type { ToastOptions, ToastTone } from './core/toast';
+export declare const nexa: {
+    render(element: HTMLElement): import("./core/renderer").RenderResult;
+    renderPage(commands: string, target: HTMLElement): import("./core/renderer").RenderResult;
+    mount(root?: Element | Document): import("./core/renderer").RenderResult;
+} & {
+    toast: typeof pushToast;
+    clearToasts: typeof clearToasts;
+};
+export { createNexa, registry, registerPrototypeComponents, applyColorMap, applyColorSeed, colorMapNames, generateBrandScale, applyBrandScale, applyBrandColor, exportBrandScaleCss, normalizeHex, mapPresets, resolveMapSeed, saveBrandMap, deleteSavedMap, listSavedMapNames, getSavedMaps, normalizeMapName };
+export { pushToast, clearToasts };
+export type { ToastOptions, ToastTone };
+export { NEXA_ASSETS } from './core/brand-assets';
+export type { NexaAssetKey } from './core/brand-assets';
+export type { NexaCommand } from './core/parser';
+export type { ColorMapName, BrandScale, BrandStep } from './core/colormap';
+export { componentSchemas, getComponentSchema } from './core/schema';
+export { validateModifiers } from './core/validate';
+export { wireBehaviors } from './core/behaviors';
+export { buildNexaChartOption, NEXA_ECHARTS_THEME } from './core/echarts-nexa';
+export declare function wireEcharts(root?: ParentNode): Promise<void>;
+export declare function mountNexaChart(host: HTMLElement): Promise<import("echarts").ECharts | null>;
+export { renderIcon, renderCardIcon, hasNexaIcon, listNexaIconNames } from './components/icons';
+export type { NexaIconWeight } from './components/icons';
+export { CARD_LAYOUTS, CARD_MODELS, CARD_STYLES } from './components/card';
+export type { CardModel } from './components/card';
+export type { CardLayout } from './components/card-layouts';