forge-select 0.2.0 → 0.4.0

package/README.md

@@ -1,4 +1,4 @@
-# ForgeSelect
+# Forge Select
 
 [![npm version](https://img.shields.io/npm/v/forge-select.svg)](https://www.npmjs.com/package/forge-select)
 [![CI](https://github.com/cmm-cmm/ForgeSelect/actions/workflows/ci.yml/badge.svg)](https://github.com/cmm-cmm/ForgeSelect/actions/workflows/ci.yml)
@@ -6,13 +6,13 @@
 
 «A modern, lightweight, highly customizable replacement for Select2.»
 
-ForgeSelect is a next-generation JavaScript select component built for modern web applications. It provides a clean API, powerful customization options, excellent performance, and accessibility while remaining framework-agnostic.
+Forge Select is a next-generation JavaScript select component built for modern web applications. It provides a clean API, powerful customization options, excellent performance, and accessibility while remaining framework-agnostic.
 
-## Why ForgeSelect?
+## Why Forge Select?
 
 Select2 has served the community well for many years, but modern web development has evolved.
 
-ForgeSelect is designed to provide:
+Forge Select is designed to provide:
 
 - 🚀 High performance
 - 🎨 Fully customizable UI
@@ -29,13 +29,13 @@ ForgeSelect is designed to provide:
 
 ## Documentation
 
-Browse the documentation website at **<https://cmm-cmm.github.io/ForgeSelect/docs/>**, or read the sources in [`docs/`](./docs/README.md):
+Browse the documentation website at **<https://forgeselect.konexforge.com/docs/>**, or read the sources in [`docs/`](./docs/README.md):
 
 - [API Reference](./docs/api-reference.md) — constructor, options, methods, events
 - [Examples](./docs/examples.md) — copy-pasteable snippets for every feature and framework
-- [Playground](./docs/playground.md) — [live demo](https://cmm-cmm.github.io/ForgeSelect/demo/) on GitHub Pages
+- [Playground](./docs/playground.md) — [live demo](https://forgeselect.konexforge.com/demo/)
 - [Migration from Select2](./docs/migration-from-select2.md) — option/event/method mapping and a migration checklist
-- [Benchmarks](./docs/benchmarks.md) — performance methodology and results (planned)
+- [Benchmarks](./docs/benchmarks.md) — reproducible bundle, initialization, search, and scrolling baseline
 - [Plugin Development Guide](./docs/plugin-development.md) — write and register your own plugins
 
 ## Features
@@ -52,6 +52,7 @@ Browse the documentation website at **<https://cmm-cmm.github.io/ForgeSelect/doc
 - Disabled Options
 - Option Groups
 - Tree Select (nested options with expand/collapse and cascading multi-select)
+- Drag & Drop Tag Ordering (reorder a multi-select's selected tags by mouse/touch/pen, or Alt+Left/Alt+Right on keyboard)
 - Clear Selection
 - Placeholder
 - Custom Themes (CSS variables, dark mode included)
@@ -60,7 +61,7 @@ Browse the documentation website at **<https://cmm-cmm.github.io/ForgeSelect/doc
 - Internationalization (en/vi built in, custom string tables)
 - TypeScript Support (written in strict TypeScript, ships `.d.ts`)
 
-> Planned/in-progress capabilities — Drag & Drop Ordering and Angular/Svelte wrappers — are tracked in the [Roadmap](#roadmap) below and intentionally not listed above as shipped features.
+> Planned/in-progress capabilities — Angular/Svelte wrappers — are tracked in the [Roadmap](#roadmap) below and intentionally not listed above as shipped features.
 
 ## Installation
 
@@ -76,9 +77,9 @@ pnpm add forge-select
 
 ```html
 <select id="country">
-    <option value="vn">Vietnam</option>
-    <option value="jp">Japan</option>
-    <option value="us">United States</option>
+  <option value="vn">Vietnam</option>
+  <option value="jp">Japan</option>
+  <option value="us">United States</option>
 </select>
 ```
 
@@ -93,12 +94,12 @@ new ForgeSelect("#country");
 
 ```js
 const select = new ForgeSelect("#country", {
-    placeholder: "Select a country",
-    searchable: true,
-    multiple: false,
-    clearable: true,
-    allowCreate: false,
-    theme: "default"
+  placeholder: "Select a country",
+  searchable: true,
+  multiple: false,
+  clearable: true,
+  allowCreate: false,
+  theme: "default",
 });
 ```
 
@@ -107,24 +108,27 @@ See the [API Reference](./docs/api-reference.md) for all options, including `dat
 ## Events
 
 ```js
-select.on("change", value => console.log(value));
+select.on("change", (value) => console.log(value));
 select.on("open", () => {});
 select.on("close", () => {});
-select.on("search", query => console.log("searching:", query));
+select.on("search", (query) => console.log("searching:", query));
 select.on("clear", () => {});
+select.on("error", (error) => console.error(error));
 ```
 
 Unsubscribe with `select.off(event, handler)`.
 
+Use `select.setValue(value, { emitChange: false })` to synchronize external controlled state without emitting `change`.
+
 ## Examples
 
 ```js
 new ForgeSelect("#users", {
-    ajax: {
-        url: query => `/api/users?q=${encodeURIComponent(query)}`,
-        debounce: 300,
-        transform: response => response.items.map(u => ({ value: u.id, label: u.name }))
-    }
+  ajax: {
+    url: (query) => `/api/users?q=${encodeURIComponent(query)}`,
+    debounce: 300,
+    transform: (response) => response.items.map((u) => ({ value: u.id, label: u.name })),
+  },
 });
 ```
 
@@ -132,16 +136,34 @@ More copy-pasteable snippets (multi-select, tags, custom templates, virtual scro
 
 ## Playground
 
-Write and run ForgeSelect code in the browser at **<https://cmm-cmm.github.io/ForgeSelect/playground/>** — with presets for every major feature. A curated feature showcase also lives at **<https://cmm-cmm.github.io/ForgeSelect/demo/>**. See [`docs/playground.md`](./docs/playground.md) for details and local setup.
+Write and run Forge Select code in the browser at **<https://forgeselect.konexforge.com/playground/>** — with presets for every major feature. A curated feature showcase also lives at **<https://forgeselect.konexforge.com/demo/>**. See [`docs/playground.md`](./docs/playground.md) for details and local setup.
 
 ## API Reference
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `placeholder` | `string` | `""` | Text shown when nothing is selected |
-| `searchable` | `boolean` | `true` | Show a search input in the dropdown |
-| `multiple` | `boolean` | `false` | Allow selecting more than one option |
-| `theme` | `string` | `"default"` | Named theme applied to the control |
+| Option                | Type                               | Default     | Description                                         |
+| --------------------- | ---------------------------------- | ----------- | --------------------------------------------------- |
+| `placeholder`         | `string`                           | `""`        | Text shown when nothing is selected                 |
+| `searchable`          | `boolean`                          | `true`      | Show a search input in the dropdown                 |
+| `multiple`            | `boolean`                          | `false`     | Allow selecting more than one option                |
+| `clearable`           | `boolean`                          | `false`     | Show a button to clear the current selection        |
+| `allowCreate`         | `boolean`                          | `false`     | Let the user create a new option from free text     |
+| `sortable`            | `boolean`                          | `false`     | Multi-select: let the user reorder selected tags    |
+| `closeOnSelect`       | `boolean`                          | `false`     | Multi-select: close the dropdown after each pick    |
+| `maxSelections`       | `number`                           | `undefined` | Multi-select: caps the number of selected values    |
+| `theme`               | `string`                           | `"default"` | Named theme applied to the control                  |
+| `required`            | `boolean`                          | `false`     | Native form validation on a `<select>` mount        |
+| `data`                | `Array<Option \| OptionGroup>`     | `undefined` | Static options, used instead of `<option>` children |
+| `ajax`                | `AjaxConfig`                       | `undefined` | Remote data source config                           |
+| `filterOption`        | `(option, query) => boolean`       | `undefined` | Custom match predicate for search filtering         |
+| `minSearchLength`     | `number`                           | `0`         | Minimum query length before filtering/ajax runs     |
+| `minResultsForSearch` | `number`                           | `0`         | Hide local search below an option-count threshold   |
+| `isOptionDisabled`    | `(option) => boolean`              | `undefined` | Dynamically disable an option per render            |
+| `virtualScroll`       | `boolean`                          | _(auto)_    | Virtualize the list once it exceeds ~100 rows       |
+| `itemHeight`          | `number`                           | `36`        | Row height in px used by the virtual scroller       |
+| `language`            | `string \| Record<string, string>` | `"en"`      | Locale code or a custom string table for i18n       |
+| `plugins`             | `Array<ForgeSelectPlugin>`         | `[]`        | Plugins to register on this instance                |
+| `openOnFocus`         | `boolean`                          | `false`     | Open the dropdown on keyboard focus                 |
+| `dropdownParent`      | `HTMLElement \| string`            | `undefined` | Portal container for overflow-constrained layouts   |
 
 Full constructor signature, all options, instance methods, and events are documented in [`docs/api-reference.md`](./docs/api-reference.md).
 
@@ -155,18 +177,18 @@ new ForgeSelect("#country", { theme: "dark" });
 
 ```css
 .forge-select {
-    --fs-border-focus: #e11d48;
-    --fs-radius: 4px;
+  --fs-border-focus: #e11d48;
+  --fs-radius: 4px;
 }
 ```
 
 ## Framework Support
 
-ForgeSelect is vanilla TypeScript/JavaScript, so it can be mounted inside any framework today. Official wrapper packages exist for a couple of them:
+Forge Select is vanilla TypeScript/JavaScript, so it can be mounted inside any framework today. Official wrapper packages exist for a couple of them:
 
 - Vanilla JavaScript
-- React — via [`@forge-select/react`](./packages/react/README.md) (`ForgeSelectReact` component, controlled `value`/`onChange`)
-- Vue — via [`@forge-select/vue`](./packages/vue/README.md) (`ForgeSelectVue` component, `v-model` support)
+- React — via [`forge-select-react`](./packages/react/README.md) (`ForgeSelectReact` component, controlled `value`/`onChange`)
+- Vue — via [`forge-select-vue`](./packages/vue/README.md) (`ForgeSelectVue` component, `v-model` support)
 - Angular — mount manually for now; a dedicated wrapper is on the [Roadmap](#roadmap)
 - Svelte — mount manually for now; a dedicated wrapper is on the [Roadmap](#roadmap)
 - Next.js
@@ -183,18 +205,18 @@ ForgeSelect is vanilla TypeScript/JavaScript, so it can be mounted inside any fr
 
 ## Migration from Select2
 
-ForgeSelect is designed as a drop-in-concept replacement for Select2: no jQuery dependency, native accessibility, and a smaller API surface. A full option/event/method mapping table and a step-by-step migration checklist are available in [`docs/migration-from-select2.md`](./docs/migration-from-select2.md).
+Forge Select is designed as a drop-in-concept replacement for Select2: no jQuery dependency, native accessibility, and a smaller API surface. A full option/event/method mapping table and a step-by-step migration checklist are available in [`docs/migration-from-select2.md`](./docs/migration-from-select2.md).
 
 ## Benchmarks
 
-Performance benchmarking (bundle size, init time, search latency, virtual scroll performance) against Select2 is planned once the first release ships. Methodology and the results format are documented in [`docs/benchmarks.md`](./docs/benchmarks.md).
+Run `npm run bench` for a reproducible JSON baseline covering bundle size, initialization, 10,000-option search latency, and virtual-scroll performance. The methodology and result fields are documented in [`docs/benchmarks.md`](./docs/benchmarks.md).
 
 ## Roadmap
 
 - [x] Tree Select
 - [x] Virtualized List
 - [x] Async Pagination
-- [ ] Drag & Drop Ordering
+- [x] Drag & Drop Ordering
 - [x] Theme Builder
 - [x] CSS Variables
 - [x] React Component
@@ -204,7 +226,7 @@ Performance benchmarking (bundle size, init time, search latency, virtual scroll
 
 ## Plugin Development Guide
 
-ForgeSelect uses a small plugin architecture (`onInit`, `onOpen`, `onClose`, `onDestroy` lifecycle hooks) so behavior can be extended without forking the core. See [`docs/plugin-development.md`](./docs/plugin-development.md) for the plugin interface and a complete example plugin.
+Forge Select uses a small plugin architecture (`onInit`, `onOpen`, `onClose`, `onDestroy` lifecycle hooks) so behavior can be extended without forking the core. See [`docs/plugin-development.md`](./docs/plugin-development.md) for the plugin interface and a complete example plugin.
 
 ## Development