native-document 1.0.168 → 1.0.169

package/docs/components/icons.md

@@ -0,0 +1,321 @@
+---
+title: Icons
+description: Adapter-based icon system with chainable API and support for Tabler, Phosphor, and Google Material Icons
+---
+
+# Icons
+
+NativeDocument provides an adapter-based icon system. Icon names are semantic and stable - switching from one icon library to another requires changing only the adapter and the CSS import.
+
+```javascript
+// Usage - always via the Icon namespace
+Icon.search.fill()
+Icon.star.fill().large()
+Icon.arrowRight.bold().color('red')
+Icon.user.fill().size(32)
+```
+
+---
+
+## Setup
+
+### 1. Register the adapter
+
+In your app entry point (`main.js`):
+
+```javascript
+import { Icon }         from 'native-document/icons';
+import TablerIconRender from 'native-document/ui/icon/tabler';
+
+Icon.use(TablerIconRender, {
+    variant: 'outline',  // default variant
+    size:    'medium',   // default size: small | medium | large | extraLarge
+});
+```
+
+### 2. Import the CSS
+
+In the same entry point, import the icon font alongside your theme:
+
+```javascript
+// main.js
+import 'native-document/src/ui/theme.scss';
+import '@tabler/icons-webfont/dist/tabler-icons.css';
+```
+
+---
+
+## Methods
+
+### Variants
+
+| Method | Sets variant to |
+|---|---|
+| `.thin()` | `'thin'` |
+| `.light()` | `'light'` |
+| `.regular()` | `'regular'` |
+| `.bold()` | `'bold'` |
+| `.fill()` | `'fill'` |
+| `.duotone()` | `'duotone'` |
+| `.variant(name)` | any custom string |
+
+### Sizes
+
+| Method | Sets size to |
+|---|---|
+| `.small()` | `'small'` - 16px |
+| `.medium()` | `'medium'` - 24px |
+| `.large()` | `'large'` - 32px |
+| `.extraLarge()` | `'extraLarge'` - 48px |
+| `.size(value)` | number in px or named string |
+
+### Other
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.color(value)` | `value: string` | CSS color value |
+| `.weight(value)` | `value: string` | Stroke weight (adapter-dependent) |
+
+All methods accept `Observable` values - the icon updates automatically when the observable changes:
+
+```javascript
+const isDark = Observable(false);
+
+Icon.star
+    .variant(isDark.transform((d) => d ? 'fill' : 'outline'))
+    .color(isDark.transform((d) => d ? 'gold' : 'currentColor'))
+```
+
+---
+
+## Available icons
+
+> The standard set covers the most common use cases. Each adapter maps these names to its own icon names - not every icon exists in every library.
+
+### Navigation
+`Icon.arrowLeft`, `Icon.arrowRight`, `Icon.arrowUp`, `Icon.arrowDown`, `Icon.chevronLeft`, `Icon.chevronRight`, `Icon.chevronUp`, `Icon.chevronDown`, `Icon.home`, `Icon.menu`, `Icon.close`, `Icon.back`, `Icon.forward`, `Icon.expand`, `Icon.collapse`, `Icon.fullscreen`, `Icon.fullscreenExit`
+
+### Actions
+`Icon.search`, `Icon.filter`, `Icon.sort`, `Icon.edit`, `Icon.delete`, `Icon.add`, `Icon.remove`, `Icon.save`, `Icon.copy`, `Icon.download`, `Icon.upload`, `Icon.share`, `Icon.refresh`, `Icon.more`, `Icon.settings`, `Icon.drag`, `Icon.resize`, `Icon.undo`, `Icon.redo`, `Icon.scan`, `Icon.print`, `Icon.import`, `Icon.export`
+
+### Feedback
+`Icon.check`, `Icon.checkCircle`, `Icon.error`, `Icon.warning`, `Icon.info`, `Icon.help`, `Icon.loading`, `Icon.success`
+
+### User
+`Icon.user`, `Icon.userCircle`, `Icon.users`, `Icon.lock`, `Icon.unlock`, `Icon.eye`, `Icon.eyeOff`, `Icon.bell`, `Icon.notification`
+
+### Files & Media
+`Icon.file`, `Icon.folder`, `Icon.image`, `Icon.document`, `Icon.attachment`, `Icon.link`, `Icon.externalLink`, `Icon.play`, `Icon.pause`, `Icon.stop`, `Icon.mute`, `Icon.sound`, `Icon.video`, `Icon.camera`
+
+### Interface
+`Icon.grid`, `Icon.list`, `Icon.calendar`, `Icon.clock`, `Icon.tag`, `Icon.tags`, `Icon.qrCode`, `Icon.barcode`
+
+### Text editing
+`Icon.bold`, `Icon.italic`, `Icon.underline`, `Icon.strikethrough`, `Icon.alignLeft`, `Icon.alignCenter`, `Icon.alignRight`, `Icon.alignJustify`, `Icon.orderedList`, `Icon.unorderedList`, `Icon.indent`, `Icon.outdent`, `Icon.scissors`, `Icon.fontColor`, `Icon.highlight`
+
+### Data & charts
+`Icon.barChart`, `Icon.lineChart`, `Icon.pieChart`, `Icon.areaChart`, `Icon.table`, `Icon.database`
+
+### Commerce & finance
+`Icon.shoppingCart`, `Icon.creditCard`, `Icon.wallet`, `Icon.bank`, `Icon.gift`, `Icon.percentage`, `Icon.dollar`, `Icon.euro`
+
+### Communication
+`Icon.mail`, `Icon.message`, `Icon.comment`, `Icon.phone`
+
+### System & dev
+`Icon.cloud`, `Icon.cloudUpload`, `Icon.cloudDownload`, `Icon.api`, `Icon.code`, `Icon.bug`, `Icon.tool`, `Icon.robot`
+
+### Location
+`Icon.map`, `Icon.compass`, `Icon.global`, `Icon.location`
+
+### Shapes & objects
+`Icon.star`, `Icon.heart`, `Icon.flag`, `Icon.trophy`, `Icon.medal`, `Icon.rocket`, `Icon.fire`, `Icon.thunder`, `Icon.smile`, `Icon.frown`, `Icon.like`, `Icon.dislike`, `Icon.safety`, `Icon.key`
+
+---
+
+## Custom icons
+
+Create your own renderer that wraps the base adapter. Use NativeDocument elements for reactive support:
+
+```javascript
+import { Img, Span, ShowIf } from 'native-document/elements';
+import TablerIconRender from 'native-document/ui/icon/tabler/TablerIconRender';
+
+function MyIconRender($desc) {
+    // Handle your custom icons
+    if ($desc.name === 'logo' || $desc.name === 'dashboard') {
+        const size = $desc.size?.__$Observable
+            ? $desc.size.transform((s) => typeof s === 'number' ? `${s}px` : `${SIZES[s] ?? 24}px`)
+            : `${typeof $desc.size === 'number' ? $desc.size : 24}px`;
+
+        return Img({
+            src: `/icons/${$desc.name}.svg`,
+            'aria-hidden': 'true',
+            style: {
+                width:  size,
+                height: size,
+                color:  $desc.color ?? 'currentColor',
+            },
+        });
+    }
+
+    // Fall back to Tabler for everything else
+    return TablerIconRender($desc);
+}
+
+Icon.use(MyIconRender, { size: 'medium' });
+```
+
+---
+
+## Adapters
+
+### Tabler Icons
+
+> Outline and filled variants - the standard set covers the most common icons from Tabler's library.
+
+**Install**
+
+```bash
+npm install @tabler/icons-webfont
+```
+
+**main.js**
+
+```javascript
+import { Icon }         from 'native-document/icons';
+import TablerIconRender from 'native-document/ui/icon/tabler';
+import 'native-document/src/ui/theme.scss';
+import '@tabler/icons-webfont/dist/tabler-icons.css';
+
+// Uncomment to enable .fill() variant
+// import '@tabler/icons-webfont/dist/tabler-icons-filled.css';
+
+Icon.use(TablerIconRender, { variant: 'outline', size: 'medium' });
+```
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `outline` (default) | Stroked icons | `tabler-icons.css` |
+| `fill` | Filled icons | `tabler-icons-filled.css` |
+
+**Example**
+
+```javascript
+Icon.search              // outline, medium
+Icon.search.fill()       // filled
+Icon.star.fill().large() // filled, 32px
+```
+
+---
+
+### Phosphor Icons
+
+> 6 weights - the standard set covers the most common icons from Phosphor's library.
+
+**Install**
+
+```bash
+npm install @phosphor-icons/web
+```
+
+**main.js**
+
+```javascript
+import { Icon }           from 'native-document/icons';
+import PhosphorIconRender from 'native-document/ui/icon/phosphor';
+import 'native-document/src/ui/theme.scss';
+
+// Check the exact path in your node_modules/@phosphor-icons/web/ directory
+import '@phosphor-icons/web/src/regular/style.css';
+
+// Import only the weights you need
+// import '@phosphor-icons/web/src/thin/style.css';
+// import '@phosphor-icons/web/src/light/style.css';
+// import '@phosphor-icons/web/src/bold/style.css';
+// import '@phosphor-icons/web/src/fill/style.css';
+// import '@phosphor-icons/web/src/duotone/style.css';
+
+Icon.use(PhosphorIconRender, { variant: 'regular', size: 'medium' });
+```
+
+> The CSS path may vary depending on the installed version. If you get a resolve error, run `ls node_modules/@phosphor-icons/web/` to find the correct path.
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `thin` | Thinnest stroke | `thin/style.css` |
+| `light` | Light stroke | `light/style.css` |
+| `regular` (default) | Standard stroke | `regular/style.css` |
+| `bold` | Bold stroke | `bold/style.css` |
+| `fill` | Filled | `fill/style.css` |
+| `duotone` | Two-tone | `duotone/style.css` |
+
+**Example**
+
+```javascript
+Icon.search                // regular, medium
+Icon.search.bold()         // bold
+Icon.star.fill().large()   // filled, 32px
+Icon.heart.duotone()       // duotone
+```
+
+---
+
+### Google Material Icons
+
+> Filled, outlined, round, sharp, two-tone - the standard set covers the most common icons from Material's library.
+
+**Install**
+
+```bash
+npm install material-icons
+```
+
+**main.js**
+
+```javascript
+import { Icon }           from 'native-document/icons';
+import MaterialIconRender from 'native-document/ui/icon/material';
+import 'native-document/src/ui/theme.scss';
+import 'material-icons/iconfont/filled.css';
+
+// Import only the styles you need
+// import 'material-icons/iconfont/outlined.css';
+// import 'material-icons/iconfont/round.css';
+// import 'material-icons/iconfont/sharp.css';
+// import 'material-icons/iconfont/two-tone.css';
+
+Icon.use(MaterialIconRender, { variant: 'fill', size: 'medium' });
+```
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `fill` / `regular` (default) | Filled icons | `filled.css` |
+| `outline` | Outlined icons | `outlined.css` |
+| `round` | Rounded icons | `round.css` |
+| `sharp` | Sharp corners | `sharp.css` |
+| `twoTone` | Two-tone icons | `two-tone.css` |
+
+> Material Icons uses **ligatures** - the icon name is the text content of the element, converted to an icon by the font. This is handled automatically by the renderer.
+
+**Example**
+
+```javascript
+Icon.search                       // filled, medium
+Icon.search.variant('outline')    // outlined
+Icon.star.large()                 // filled, 32px
+```
+
+---
+
+## Next Steps
+
+- **[Components Overview](./index.md)** - BaseComponent and renderer pattern
+- **[Getting Started](./getting-started.md)** - Register default renderers
+- **[Theming](../theming.md)** - CSS tokens reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-document",
-  "version": "1.0.168",
+  "version": "1.0.169",
   "description": "A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features",
   "author": "AfroCodeur <https://github.com/afrocodeur>",
   "license": "MIT",

package/src/components/form/field/types/FileField.js

@@ -13,7 +13,7 @@ import FileItemPreview from '../../field/types/file-field-mode/FileItemPreview';
  *     .accept(['application/pdf', 'image/png'])
  *     .maxSize(5 * 1024 * 1024, 'Max 5MB per file')
  *     .maxFiles(3, 'Max 3 files')
- *     .mode('dropzone')
+ *     .mode(FileDropzoneMode())
  *     .onFileAdd((file) => console.log('added', file.name))
  *     .onFileRemove((file) => console.log('removed', file.name));
  *
@@ -54,7 +54,7 @@ FileField.defaultTemplate = null;
  *     label: NdChild|null,
  *     accept: string|null,
  *     multiple: boolean,
- *     mode: 'native'|'dropzone'|'button'|'wall'|'avatar'|null,
+ *     mode: FileNativeMode|FileAvatarMode|FileDropzoneMode|FileUploadButtonMode|FileWallMode|null,
  *     files: Observable<FileItemPreview[]>,
  *     fileIcons: Array<(file: File) => NdChild>,
  *     disabled: boolean|Observable<boolean>,
@@ -91,7 +91,7 @@ FileField.prototype.multiple = function(enabled = true) {
 };
 
 /**
- * @param {'native'|'dropzone'|'button'|'wall'|'avatar'} mode
+ * @param {FileNativeMode|FileAvatarMode|FileDropzoneMode|FileUploadButtonMode|FileWallMode|null} mode
  * @returns {this}
  */
 FileField.prototype.mode = function(mode) {

package/src/components/icon/Icon.js

@@ -0,0 +1,107 @@
+import BaseComponent from '../BaseComponent';
+
+/**
+ * @constructor
+ * @param {string} name
+ * @param {object} [props={}]
+ */
+export function Icon(name, props = {}) {
+    if(!(this instanceof Icon)) {
+        return new Icon(name, props);
+    }
+
+    BaseComponent.call(this, {});
+
+    this.$description = {
+        name,
+        variant: null,
+        color:   null,
+        weight:  null,
+        size:    null,
+        ...props,
+    };
+}
+
+BaseComponent.extends(Icon);
+
+Icon.defaultTemplate = null;
+Icon.defaultConfigs  = null;
+
+/**
+ * @param {(description, instance: Icon) => NdChild} template
+ * @param {{ variant?: string, size?: string, color?: string, weight?: string }} [defaultConfigs={}]
+ */
+Icon.use = function(template, defaultConfigs = {}) {
+    Icon.defaultTemplate = template;
+    Icon.defaultConfigs  = defaultConfigs;
+};
+
+Icon.prototype.variant = function(variant) {
+    this.$description.variant = variant;
+    return this;
+};
+
+Icon.prototype.thin = function() {
+    this.$description.variant = 'thin';
+    return this;
+};
+
+Icon.prototype.light = function() {
+    this.$description.variant = 'light';
+    return this;
+};
+
+Icon.prototype.regular = function() {
+    this.$description.variant = 'regular';
+    return this;
+};
+
+Icon.prototype.bold = function() {
+    this.$description.variant = 'bold';
+    return this;
+};
+
+Icon.prototype.fill = function() {
+    this.$description.variant = 'fill';
+    return this;
+};
+
+Icon.prototype.duotone = function() {
+    this.$description.variant = 'duotone';
+    return this;
+};
+
+Icon.prototype.weight = function(weight) {
+    this.$description.weight = weight;
+    return this;
+};
+
+Icon.prototype.size = function(size) {
+    this.$description.size = size;
+    return this;
+};
+
+Icon.prototype.small = function() {
+    this.$description.size = 'small';
+    return this;
+};
+
+Icon.prototype.medium = function() {
+    this.$description.size = 'medium';
+    return this;
+};
+
+Icon.prototype.large = function() {
+    this.$description.size = 'large';
+    return this;
+};
+
+Icon.prototype.extraLarge = function() {
+    this.$description.size = 'extraLarge';
+    return this;
+};
+
+Icon.prototype.color = function(color) {
+    this.$description.color = color;
+    return this;
+};

package/src/components/icon/icon-getters.js

@@ -0,0 +1,142 @@
+import * as ICONS from './icons';
+
+export const ICON_GETTERS = {
+    arrowLeft:      ICONS.ICON_ARROW_LEFT,
+    arrowRight:     ICONS.ICON_ARROW_RIGHT,
+    arrowUp:        ICONS.ICON_ARROW_UP,
+    arrowDown:      ICONS.ICON_ARROW_DOWN,
+    chevronLeft:    ICONS.ICON_CHEVRON_LEFT,
+    chevronRight:   ICONS.ICON_CHEVRON_RIGHT,
+    chevronUp:      ICONS.ICON_CHEVRON_UP,
+    chevronDown:    ICONS.ICON_CHEVRON_DOWN,
+    home:           ICONS.ICON_HOME,
+    menu:           ICONS.ICON_MENU,
+    close:          ICONS.ICON_CLOSE,
+    back:           ICONS.ICON_BACK,
+    forward:        ICONS.ICON_FORWARD,
+    expand:         ICONS.ICON_EXPAND,
+    collapse:       ICONS.ICON_COLLAPSE,
+    fullscreen:     ICONS.ICON_FULLSCREEN,
+    fullscreenExit: ICONS.ICON_FULLSCREEN_EXIT,
+    search:         ICONS.ICON_SEARCH,
+    filter:         ICONS.ICON_FILTER,
+    sort:           ICONS.ICON_SORT,
+    edit:           ICONS.ICON_EDIT,
+    delete:         ICONS.ICON_DELETE,
+    add:            ICONS.ICON_ADD,
+    remove:         ICONS.ICON_REMOVE,
+    save:           ICONS.ICON_SAVE,
+    copy:           ICONS.ICON_COPY,
+    download:       ICONS.ICON_DOWNLOAD,
+    upload:         ICONS.ICON_UPLOAD,
+    share:          ICONS.ICON_SHARE,
+    refresh:        ICONS.ICON_REFRESH,
+    more:           ICONS.ICON_MORE,
+    settings:       ICONS.ICON_SETTINGS,
+    drag:           ICONS.ICON_DRAG,
+    resize:         ICONS.ICON_RESIZE,
+    undo:           ICONS.ICON_UNDO,
+    redo:           ICONS.ICON_REDO,
+    scan:           ICONS.ICON_SCAN,
+    print:          ICONS.ICON_PRINT,
+    import:         ICONS.ICON_IMPORT,
+    export:         ICONS.ICON_EXPORT,
+    check:          ICONS.ICON_CHECK,
+    checkCircle:    ICONS.ICON_CHECK_CIRCLE,
+    error:          ICONS.ICON_ERROR,
+    warning:        ICONS.ICON_WARNING,
+    info:           ICONS.ICON_INFO,
+    help:           ICONS.ICON_HELP,
+    loading:        ICONS.ICON_LOADING,
+    success:        ICONS.ICON_SUCCESS,
+    user:           ICONS.ICON_USER,
+    userCircle:     ICONS.ICON_USER_CIRCLE,
+    users:          ICONS.ICON_USERS,
+    lock:           ICONS.ICON_LOCK,
+    unlock:         ICONS.ICON_UNLOCK,
+    eye:            ICONS.ICON_EYE,
+    eyeOff:         ICONS.ICON_EYE_OFF,
+    bell:           ICONS.ICON_BELL,
+    notification:   ICONS.ICON_NOTIFICATION,
+    file:           ICONS.ICON_FILE,
+    folder:         ICONS.ICON_FOLDER,
+    image:          ICONS.ICON_IMAGE,
+    document:       ICONS.ICON_DOCUMENT,
+    attachment:     ICONS.ICON_ATTACHMENT,
+    link:           ICONS.ICON_LINK,
+    externalLink:   ICONS.ICON_EXTERNAL_LINK,
+    play:           ICONS.ICON_PLAY,
+    pause:          ICONS.ICON_PAUSE,
+    stop:           ICONS.ICON_STOP,
+    mute:           ICONS.ICON_MUTE,
+    sound:          ICONS.ICON_SOUND,
+    video:          ICONS.ICON_VIDEO,
+    camera:         ICONS.ICON_CAMERA,
+    grid:           ICONS.ICON_GRID,
+    list:           ICONS.ICON_LIST,
+    calendar:       ICONS.ICON_CALENDAR,
+    clock:          ICONS.ICON_CLOCK,
+    tag:            ICONS.ICON_TAG,
+    tags:           ICONS.ICON_TAGS,
+    qrCode:         ICONS.ICON_QR_CODE,
+    barcode:        ICONS.ICON_BARCODE,
+    bold:           ICONS.ICON_BOLD,
+    italic:         ICONS.ICON_ITALIC,
+    underline:      ICONS.ICON_UNDERLINE,
+    strikethrough:  ICONS.ICON_STRIKETHROUGH,
+    alignLeft:      ICONS.ICON_ALIGN_LEFT,
+    alignCenter:    ICONS.ICON_ALIGN_CENTER,
+    alignRight:     ICONS.ICON_ALIGN_RIGHT,
+    alignJustify:   ICONS.ICON_ALIGN_JUSTIFY,
+    orderedList:    ICONS.ICON_ORDERED_LIST,
+    unorderedList:  ICONS.ICON_UNORDERED_LIST,
+    indent:         ICONS.ICON_INDENT,
+    outdent:        ICONS.ICON_OUTDENT,
+    scissors:       ICONS.ICON_SCISSORS,
+    fontColor:      ICONS.ICON_FONT_COLOR,
+    highlight:      ICONS.ICON_HIGHLIGHT,
+    barChart:       ICONS.ICON_BAR_CHART,
+    lineChart:      ICONS.ICON_LINE_CHART,
+    pieChart:       ICONS.ICON_PIE_CHART,
+    areaChart:      ICONS.ICON_AREA_CHART,
+    table:          ICONS.ICON_TABLE,
+    database:       ICONS.ICON_DATABASE,
+    shoppingCart:   ICONS.ICON_SHOPPING_CART,
+    creditCard:     ICONS.ICON_CREDIT_CARD,
+    wallet:         ICONS.ICON_WALLET,
+    bank:           ICONS.ICON_BANK,
+    gift:           ICONS.ICON_GIFT,
+    percentage:     ICONS.ICON_PERCENTAGE,
+    dollar:         ICONS.ICON_DOLLAR,
+    euro:           ICONS.ICON_EURO,
+    mail:           ICONS.ICON_MAIL,
+    message:        ICONS.ICON_MESSAGE,
+    comment:        ICONS.ICON_COMMENT,
+    phone:          ICONS.ICON_PHONE,
+    cloud:          ICONS.ICON_CLOUD,
+    cloudUpload:    ICONS.ICON_CLOUD_UPLOAD,
+    cloudDownload:  ICONS.ICON_CLOUD_DOWNLOAD,
+    api:            ICONS.ICON_API,
+    code:           ICONS.ICON_CODE,
+    bug:            ICONS.ICON_BUG,
+    tool:           ICONS.ICON_TOOL,
+    robot:          ICONS.ICON_ROBOT,
+    map:            ICONS.ICON_MAP,
+    compass:        ICONS.ICON_COMPASS,
+    global:         ICONS.ICON_GLOBAL,
+    location:       ICONS.ICON_LOCATION,
+    star:           ICONS.ICON_STAR,
+    heart:          ICONS.ICON_HEART,
+    flag:           ICONS.ICON_FLAG,
+    trophy:         ICONS.ICON_TROPHY,
+    medal:          ICONS.ICON_MEDAL,
+    rocket:         ICONS.ICON_ROCKET,
+    fire:           ICONS.ICON_FIRE,
+    thunder:        ICONS.ICON_THUNDER,
+    smile:          ICONS.ICON_SMILE,
+    frown:          ICONS.ICON_FROWN,
+    like:           ICONS.ICON_LIKE,
+    dislike:        ICONS.ICON_DISLIKE,
+    safety:         ICONS.ICON_SAFETY,
+    key:            ICONS.ICON_KEY,
+};