@ekzo-dev/bootstrap-addons 5.3.20 → 5.3.22

package/README.md

@@ -1,181 +1,95 @@
-# `ui-utils`
+# @ekzo-dev/bootstrap-addons
 
-This project is bootstrapped by [aurelia-cli](https://github.com/aurelia/cli).
+Additional Bootstrap form components for Aurelia 2 applications.
 
-This Aurelia plugin project has a built-in dev app (with CLI built-in bundler and RequireJS) to simplify development.
+This package extends [@ekzo-dev/bootstrap](https://github.com/ekzo-dev/aurelia-components/tree/main/packages-adapters/bootstrap) with advanced form components that provide enhanced functionality beyond the standard Bootstrap form controls.
 
-1. The local `src/` folder, is the source code for the plugin.
-2. The local `dev-app/` folder, is the code for the dev app, just like a normal app bootstrapped by aurelia-cli.
-3. You can use normal `au run` and `au test` in development just like developing an app.
-4. You can use aurelia-testing to test your plugin, just like developing an app.
-5. To ensure compatibility to other apps, always use `PLATFORM.moduleName()` wrapper in files inside `src/`. You don't need to use the wrapper in `dev-app/` folder as CLI built-in bundler supports module name without the wrapper.
+## Installation
 
-Note aurelia-cli doesn't provide a plugin skeleton with Webpack setup (not yet), but this plugin can be consumed by any app using Webpack, or CLI built-in bundler, or jspm.
-
-## How to write an Aurelia plugin
-
-For a full length tutorial, visit [Aurelia plugin guide](https://aurelia.io/docs/plugins/write-new-plugin).
-
-Here is some basics. You can create new custom element, custom attribute, value converter or binding behavior manually, or use command `au generate` to help.
-
-```shell
-au generate element some-name
-au generate attribute some-name
-au generate value-converter some-name
-au generate binding-behavior some-name
+```bash
+npm install @ekzo-dev/bootstrap-addons
 ```
 
-By default, the cli generates command generates files in following folders:
-
-```
-src/elements
-src/attributes
-src/value-converters
-src/binding-behaviors
-```
-
-Note the folder structure is only to help you organising the files, it's not a requirement of Aurelia. You can manually create new element (or other thing) anywhere in `src/`.
-
-After you added some new file, you need to register it in `src/index.ts`. Like this:
-
-```js
-config.globalResources([
-  // ...
-  PLATFORM.moduleName('./path/to/new-file-without-ext'),
-]);
-```
-
-The usage of `PLATFORM.moduleName` wrapper is mandatory. It's needed for your plugin to be consumed by any app using webpack, CLI built-in bundler, or jspm.
-
-## Resource import within the dev app
-
-In dev app, when you need to import something from the inner plugin (for example, importing a class for dependency injection), use special name `"resources"` to reference the inner plugin.
-
-```js
-import {autoinject} from 'aurelia-framework';
-// "resources" refers the inner plugin src/index.ts
-import {MyService} from 'resources';
-
-@autoinject()
-export class App {
-  constructor(myService: MyService) {}
-}
-```
-
-## Manage dependencies
-
-By default, this plugin has no "dependencies" in package.json. Theoretically this plugin depends on at least `aurelia-pal` because `src/index.ts` imports it. It could also depends on more core Aurelia package like `aurelia-binding` or `aurelia-templating` if you build advanced components that reference them.
-
-Ideally you need to carefully add those `aurelia-pal` (`aurelia-binding`...) to "dependencies" in package.json. But in practice you don't have to. Because every app that consumes this plugin will have full Aurelia core packages installed.
-
-Furthermore, there are two benefits by leaving those dependencies out of plugin's package.json.
+### Peer Dependencies
 
-1. ensure this plugin doesn't bring in a duplicated Aurelia core package to consumers' app. This is mainly for app built with webpack. We had been hit with `aurelia-binding` v1 and v2 conflicts due to 3rd party plugin asks for `aurelia-binding` v1.
-2. reduce the burden for npm/yarn when installing this plugin.
+This package requires the following peer dependencies:
 
-If you are a perfectionist who could not stand leaving out dependencies, I recommend you to add `aurelia-pal` (`aurelia-binding`...) to "peerDependencies" in package.json. So at least it could not cause a duplicated Aurelia core package.
+- `aurelia` ^2.0.0
+- `bootstrap` ~5.3.7
+- `@popperjs/core` ^2.11.8
+- `vanilla-jsoneditor` ~3.11.0
+- `immutable-json-patch` ^6.0.1
 
-If your plugin depends on other npm package, like `lodash` or `jquery`, **you have to add them to "dependencies" in package.json**.
+## Usage
 
-## Build Plugin
+Register the plugin in your Aurelia application:
 
-Run `au build-plugin`. This will transpile all files from `src/` folder to `dist/native-modules/` and `dist/commonjs/`.
+```typescript
+import Aurelia from 'aurelia';
+import { BootstrapAddonsConfiguration } from '@ekzo-dev/bootstrap-addons';
 
-For example, `src/index.ts` will become `dist/native-modules/index.js` and `dist/commonjs/index.js`.
-
-Note all other files in `dev-app/` folder are for the dev app, they would not appear in the published npm package.
-
-## Consume Plugin
-
-By default, the `dist/` folder is not committed to git. (We have `/dist` in `.gitignore`). But that would not prevent you from consuming this plugin through direct git reference.
-
-You can consume this plugin directly by:
-
-```shell
-npm i github:your_github_username/ui-utils
-# or if you use bitbucket
-npm i bitbucket:your_github_username/ui-utils
-# or if you use gitlab
-npm i gitlab:your_github_username/ui-utils
-# or plain url
-npm i https:/github.com/your_github_username/ui-utils.git
+Aurelia
+  .register(BootstrapAddonsConfiguration)
+  .app(MyApp)
+  .start();
 ```
 
-Then load the plugin in app's `main.ts` like this.
+## Components
 
-```js
-aurelia.use.plugin('ui-utils');
-// for webpack user, use PLATFORM.moduleName wrapper
-aurelia.use.plugin(PLATFORM.moduleName('ui-utils'));
-```
+| Component | Description | Documentation |
+|-----------|-------------|---------------|
+| **Duration Input** | Form control for entering time durations in ISO 8601 format | [View docs](./src/forms/duration-input/README.md) |
+| **Select Dropdown** | Enhanced select component with improved styling and functionality | [View docs](./src/forms/select-dropdown/README.md) |
 
-The missing `dist/` files will be filled up by npm through `"prepare": "npm run build"` (in `"scripts"` section of package.json).
+## Quick Examples
 
-Yarn has a [bug](https://github.com/yarnpkg/yarn/issues/5235) that ignores `"prepare"` script. If you want to use yarn to consume your plugin through direct git reference, remove `/dist` from `.gitignore` and commit all the files. Note you don't need to commit `dist/` files if you only use yarn to consume this plugin through published npm package (`npm i ui-utils`).
+### Duration Input
 
-## Publish npm package
-
-By default, `"private"` field in package.json has been turned on, this prevents you from accidentally publish a private plugin to npm.
-
-To publish the plugin to npm for public consumption:
-
-1. Remove `"private": true,` from package.json.
-2. Pump up project version. This will run through `au test` (in "preversion" in package.json) first.
-
-```shell
-npm version patch # or minor or major
+```html
+<bs-duration-input
+  value.bind="duration"
+  label="Duration"
+  required.bind="true"
+></bs-duration-input>
 ```
 
-3. Push up changes to your git server
+### Select Dropdown
 
-```shell
-git push && git push --tags
+```html
+<bs-select-dropdown
+  value.bind="selectedValue"
+  options.bind="countries"
+  label="Country"
+></bs-select-dropdown>
 ```
 
-4. Then publish to npm, you need to have your npm account logged in.
-
-```shell
-npm publish
-```
-
-## Automate changelog, git push, and npm publish
-
-You can enable `npm version patch # or minor or major` to automatically update changelog, push commits and version tag to the git server, and publish to npm.
-
-Here is one simple setup.
-
-1. `npm i -D standard-changelog`. We use [`standard-changelog`](https://github.com/conventional-changelog/conventional-changelog) as a minimum example to support conventional changelog.
-
-- Alternatively you can use high level [standard-version](https://github.com/conventional-changelog/standard-version).
-
-2. Add two commands to `"scripts"` section of package.json.
-
-```
-"scripts": {
-  // ...
-  "version": "standard-changelog && git add CHANGELOG.md",
-  "postversion": "git push && git push --tags && npm publish"
-},
-```
+## Dependencies
 
-3. you can remove `&& npm publish` if your project is private
+This package uses:
 
-For more information, go to https://aurelia.io/docs/cli/cli-bundler
+- **@ekzo-dev/bootstrap** - Core Bootstrap components for Aurelia 2
+- **@ekzo-dev/toolkit** - Utility functions and helpers
+- **@js-temporal/polyfill** - Temporal API polyfill for date/time handling
 
-## Run dev app
+## Browser Support
 
-Run `au run`, then open `http://localhost:9000`
+This package supports all modern browsers that support ES2015+ and the following features:
 
-To open browser automatically, do `au run --open`.
+- Custom Elements (Web Components)
+- ES Modules
+- Temporal API (polyfilled)
 
-To change dev server port, do `au run --port 8888`.
+## Contributing
 
-To change dev server host, do `au run --host 127.0.0.1`
+Contributions are welcome! Please read the [contributing guidelines](https://github.com/ekzo-dev/aurelia-components/blob/main/CONTRIBUTING.md) first.
 
-**PS:** You could mix all the flags as well, `au run --host 127.0.0.1 --port 7070 --open`
+## License
 
-## Unit tests
+MIT © [Ekzo](https://github.com/ekzo-dev)
 
-Run `au test` (or `au jest`).
+## Links
 
-To run in watch mode, `au test --watch` or `au jest --watch`.
+- [GitHub Repository](https://github.com/ekzo-dev/aurelia-components)
+- [Issue Tracker](https://github.com/ekzo-dev/aurelia-components/issues)
+- [Aurelia 2 Documentation](https://docs.aurelia.io)
+- [Bootstrap 5 Documentation](https://getbootstrap.com/docs/5.3/)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ekzo-dev/bootstrap-addons",
   "description": "Aurelia Bootstrap additional component",
-  "version": "5.3.20",
+  "version": "5.3.22",
   "homepage": "https://github.com/ekzo-dev/aurelia-components/tree/main/packages/bootstrap-addons",
   "repository": {
     "type": "git",
@@ -9,22 +9,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@ekzo-dev/bootstrap": "~5.3.6",
-    "@ekzo-dev/vanilla-jsoneditor": "~3.11.0",
+    "@ekzo-dev/bootstrap": "~5.3.9",
     "@ekzo-dev/toolkit": "^1.3.0",
-    "@fortawesome/free-solid-svg-icons": "^7.0.1",
-    "@types/json-schema": "^7.0.14",
-    "@js-temporal/polyfill": "^0.5.1",
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "json-schema-library": "^11.0.0"
+    "@js-temporal/polyfill": "^0.5.1"
   },
   "peerDependencies": {
     "aurelia": "^2.0.0-rc.0",
     "bootstrap": "~5.3.7",
-    "@popperjs/core": "^2.11.8",
-    "vanilla-jsoneditor": "~3.11.0",
-    "immutable-json-patch": "^6.0.1"
+    "@popperjs/core": "^2.11.8"
   },
   "main": "src/index.ts",
   "files": [

package/src/forms/duration-input/README.md

@@ -0,0 +1,153 @@
+# Duration Input
+
+A form control for entering time durations in ISO 8601 format.
+
+## Overview
+
+The Duration Input component allows users to input time durations using separate fields for days, hours, minutes, and seconds. The component automatically converts the input to ISO 8601 duration format (e.g., `P5DT1H` for 5 days and 1 hour).
+
+## Features
+
+- ISO 8601 duration format support
+- Separate inputs for days, hours, minutes, seconds
+- Integration with Bootstrap form validation
+- Floating label support
+- Size variants (sm, lg)
+- Full Bootstrap styling
+- Inherits all BaseField functionality
+
+## Basic Usage
+
+```html
+<bs-duration-input
+  value.bind="duration"
+  label="Duration"
+></bs-duration-input>
+```
+
+```typescript
+export class MyComponent {
+  duration = 'P5DT1H30M'; // 5 days, 1 hour, 30 minutes
+}
+```
+
+## Examples
+
+### With Validation
+
+```html
+<bs-duration-input
+  value.bind="duration"
+  label="Task Duration"
+  required.bind="true"
+  invalid-feedback="Please enter a duration"
+></bs-duration-input>
+```
+
+### With Floating Label
+
+```html
+<bs-duration-input
+  value.bind="duration"
+  label="Duration"
+  floating-label.bind="true"
+  bs-size="lg"
+></bs-duration-input>
+```
+
+### Custom Validation
+
+```html
+<bs-duration-input
+  value.bind="duration"
+  label="Duration"
+  valid.bind="isValid"
+  valid-feedback="Duration is valid"
+  invalid-feedback="Duration must be at least 1 hour"
+></bs-duration-input>
+```
+
+```typescript
+export class MyComponent {
+  duration = '';
+
+  get isValid() {
+    if (!this.duration) return undefined;
+    // Check if duration is at least 1 hour
+    const match = this.duration.match(/PT(\d+)H/);
+    return match && parseInt(match[1]) >= 1;
+  }
+}
+```
+
+## Bindable Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | - | Two-way bound ISO 8601 duration string (e.g., `P5DT1H30M`) |
+| `bsSize` | `'sm' \| 'lg'` | - | Bootstrap size variant |
+| `floatingLabel` | `boolean` | `false` | Enable floating label style |
+
+### Inherited from BaseField
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `name` | `string` | - | Input name attribute |
+| `label` | `string` | - | Label text |
+| `title` | `string` | - | Title attribute |
+| `disabled` | `boolean` | `false` | Disable the input |
+| `required` | `boolean` | `false` | Mark as required |
+| `valid` | `boolean` | - | Validation state (undefined = not validated, true = valid, false = invalid) |
+| `validFeedback` | `string` | - | Valid feedback message |
+| `invalidFeedback` | `string` | - | Invalid feedback message |
+| `form` | `string` | - | Associated form id |
+| `text` | `string \| HTMLElement` | - | Helper text displayed below the input |
+
+## ISO 8601 Duration Format
+
+The component uses ISO 8601 duration format:
+
+- `P` - Period designator (required)
+- `nD` - Number of days
+- `T` - Time designator (required if hours/minutes/seconds are present)
+- `nH` - Number of hours
+- `nM` - Number of minutes
+- `nS` - Number of seconds
+
+### Examples
+
+- `P5D` - 5 days
+- `PT2H` - 2 hours
+- `PT30M` - 30 minutes
+- `P1DT6H30M` - 1 day, 6 hours, 30 minutes
+- `PT1H30M45S` - 1 hour, 30 minutes, 45 seconds
+
+## Styling
+
+The component uses standard Bootstrap form control classes and can be styled using Bootstrap utilities:
+
+```html
+<bs-duration-input
+  value.bind="duration"
+  label="Duration"
+  class="mb-3"
+  bs-size="sm"
+></bs-duration-input>
+```
+
+## Accessibility
+
+The component follows accessibility best practices:
+
+- Proper label association
+- ARIA attributes for validation states
+- Keyboard navigation support
+- Screen reader friendly
+
+## Browser Support
+
+Requires browsers that support:
+
+- ES2015+
+- Custom Elements
+- Temporal API (polyfilled)

package/src/forms/duration-input/duration-input.html

@@ -1,7 +1,7 @@
 <template class="${floatingLabel ? 'form-floating' : ''}">
   <label for.one-time="id" if.bind="label && !floatingLabel" class="form-label">${label}</label>
   <fieldset class="${classes}" disabled.bind="disabled">
-    <input type="text" id.one-time="id" value.bind="value" focus.trigger="focus()" ref="control" />
+    <input id.one-time="id" value.bind="value" focus.trigger="focus()" ref="control" />
 
     <input type="number" min="0" value.bind="duration.years" placeholder="--" />
     <span>${labels.years}</span>

package/src/forms/duration-input/duration-input.scss

@@ -43,7 +43,7 @@ bs-duration-input {
     }
   }
 
-  input[type='text'] {
+  input[id] {
     position: absolute;
     height: 100%;
     width: 100%;

package/src/forms/duration-input/duration-input.stories.ts

@@ -1,39 +1,84 @@
 import { BsButton } from '@ekzo-dev/bootstrap';
-import { createComponentTemplate, Meta, Story, StoryFnAureliaReturnType } from '@storybook/aurelia';
-
-import { selectControl } from '../../../../../.storybook/helpers';
 
 import { BsDurationInput } from '.';
 
-const meta: Meta = {
-  title: 'Ekzo / Bootstrap Addons / Forms / Duration input',
+const meta = {
+  title: 'Bootstrap Addons / Forms / Duration input',
   component: BsDurationInput,
-  args: {
-    value: 'P5DT1Hasds',
-    label: 'Duration',
-  },
+  render: () => ({
+    template: `<bs-duration-input
+      value.bind='value'
+      bs-size.bind='bsSize'
+      floating-label.bind='floatingLabel'
+      name.bind='name'
+      label.bind='label'
+      title.bind='title'
+      disabled.bind='disabled'
+      required.bind='required'
+      valid.bind='valid'
+      valid-feedback.bind='validFeedback'
+      invalid-feedback.bind='invalidFeedback'
+      form.bind='form'
+      text.bind='text'
+    ></bs-duration-input>`,
+  }),
   argTypes: {
-    bsSize: selectControl(['', 'sm', 'lg']),
+    // BsDurationInput properties
+    value: { control: 'text' },
+    bsSize: {
+      control: 'select',
+      options: ['sm', 'lg'],
+    },
+    floatingLabel: { control: 'boolean' },
+
+    // BaseField properties
+    name: { control: 'text' },
+    label: { control: 'text' },
+    title: { control: 'text' },
+    disabled: { control: 'boolean' },
+    required: { control: 'boolean' },
+    valid: { control: 'boolean' },
+    validFeedback: { control: 'text' },
+    invalidFeedback: { control: 'text' },
+    form: { control: 'text' },
+    text: { control: 'text' },
   },
 };
 
 export default meta;
 
-const Overview: Story = (args): StoryFnAureliaReturnType => ({
-  props: args,
-});
-
-const Validation: Story = (args): StoryFnAureliaReturnType => ({
-  props: args,
-  template: `<form class='was-validated'>${createComponentTemplate(
-    BsDurationInput
-  )}<br>\${value} <button bs-button>Validate</button></form>`,
-  components: [BsButton],
-});
-
-Validation.args = {
-  required: true,
+export const Overview = {
+  args: {
+    value: 'P5DT1H',
+    label: 'Duration',
+  },
 };
 
-// eslint-disable-next-line
-export { Overview, Validation };
+export const Validation = {
+  render: () => ({
+    template: `<form class='was-validated'>
+      <bs-duration-input
+        value.bind='value'
+        bs-size.bind='bsSize'
+        floating-label.bind='floatingLabel'
+        name.bind='name'
+        label.bind='label'
+        title.bind='title'
+        disabled.bind='disabled'
+        required.bind='required'
+        valid.bind='valid'
+        valid-feedback.bind='validFeedback'
+        invalid-feedback.bind='invalidFeedback'
+        form.bind='form'
+        text.bind='text'
+      ></bs-duration-input>
+      <br>\${value}
+      <button bs-button>Validate</button>
+    </form>`,
+    components: [BsButton],
+  }),
+  args: {
+    label: 'Duration',
+    required: true,
+  },
+};

package/src/forms/duration-input/duration-input.ts

@@ -7,12 +7,17 @@ import { coerceBoolean } from '@ekzo-dev/toolkit';
 import { Temporal } from '@js-temporal/polyfill';
 import { bindable, BindingMode, customElement } from 'aurelia';
 
-type Duration = Partial<Pick<Temporal.Duration, 'years' | 'months' | 'days' | 'hours' | 'minutes' | 'seconds'>>;
+type Writable<T> = {
+  -readonly [P in keyof T]: T[P];
+};
+type Duration = Writable<
+  Partial<Pick<Temporal.Duration, 'years' | 'months' | 'days' | 'hours' | 'minutes' | 'seconds'>>
+>;
 type DurationLabels = {
   [K in keyof Duration]: string;
 };
 
-const durationKeys = ['years', 'months', 'days', 'hours', 'minutes', 'seconds'] as const;
+const durationKeys: (keyof Duration)[] = ['years', 'months', 'days', 'hours', 'minutes', 'seconds'] as const;
 
 /**
  * https://github.com/whatwg/html/issues/5488
@@ -81,7 +86,7 @@ export class BsDurationInput extends BaseField implements EventListenerObject {
   }
 
   handleEvent(event: KeyboardEvent | ClipboardEvent): void {
-    const data = event instanceof KeyboardEvent ? event.key : event.clipboardData.getData('text');
+    const data = event instanceof KeyboardEvent ? event.key : event.clipboardData!.getData('text');
 
     // don't allow non-numeric values
     if (!/^\d+$/.test(data)) {
@@ -101,10 +106,10 @@ export class BsDurationInput extends BaseField implements EventListenerObject {
   private _parseDuration(value: string) {
     try {
       const duration = Temporal.Duration.from(value);
-      const result = {};
+      const result: Duration = {};
 
       durationKeys.forEach((key) => {
-        result[key] = duration[key] ? duration[key].toString() : '';
+        result[key] = duration[key] ? duration[key] : undefined;
       });
       this.duration = result;
     } catch (error) {
@@ -118,6 +123,7 @@ export class BsDurationInput extends BaseField implements EventListenerObject {
   }
 
   #getLabels(): DurationLabels {
+    // @ts-ignore
     const str: string = new Intl['DurationFormat'](navigator.language, { style: 'narrow' }).format({
       years: 1,
       months: 1,