dmonphx

Joined on 2026-02-19

@phoenix-tekhne/web-dynamis (2.5.1)

Published 2026-05-28 07:22:40 -07:00 by dmonphx

Set up this registry in your project .npmrc file:

@phoenix-tekhne:registry=https://gitrepo.cstudiosinc.com/api/packages/dmonphx/npm/

To install the package using npm, run the following command:

npm install @phoenix-tekhne/web-dynamis@2.5.1

or add it to the package.json file:

"@phoenix-tekhne/web-dynamis": "2.5.1"

For more information on the npm registry, see the documentation.

@phoenix-tekhne/web-dynamis

Web Components for headless UI interactions. Framework-agnostic Custom Elements using the Phoenix Tekhne Design System.

Installation

npm install @phoenix-tekhne/web-dynamis @phoenix-tekhne/dynamis-core

Quick Start

<!DOCTYPE html>
<html>
<head>
  <script type="module">
    import '@phoenix-tekhne/web-dynamis';
    // Or register manually:
    // import { registerAllElements } from '@phoenix-tekhne/web-dynamis';
    // registerAllElements();
  </script>
</head>
<body>
  <!-- All elements auto-register -->
  <phx-button>Click me</phx-button>
  <phx-toggle checked></phx-toggle>
  <phx-toast-container position="bottom-right">
    <!-- Toasts will appear here -->
  </phx-toast-container>
</body>
</html>

Custom Elements

Element	Greek	Purpose
`<phx-button>`	προσκρούσις (pressing against)	Button press interactions
`<phx-toggle>`	κράσις (mixing)	Toggle/checkbox state
`<phx-text-field>`	λέξις (word)	Text field validation
`<phx-select>`	ἔλλειψις (choice)	Select/dropdown interactions
`<phx-toast-container>`	κήρυγμα (proclamation)	Toast notifications

API Reference

phx-button (Press)

Handles button press interactions with pointer and keyboard support.

<!-- Basic usage -->
<phx-button id="myButton">
  Click me
</phx-button>

<!-- Disabled state -->
<phx-button disabled>
  Disabled
</phx-button>

<script>
const button = document.getElementById('myButton');

// Events
button.addEventListener('phx-press-start', (e) => {
  console.log('Press started');
});

button.addEventListener('phx-press-end', (e) => {
  console.log('Press ended');
});

button.addEventListener('phx-press', (e) => {
  console.log('Button pressed!');
});

// API methods
button.press();     // Programmatically trigger press
button.reset();    // Reset to initial state

// Properties
button.isDisabled;  // boolean - whether disabled
</script>

<style>
phx-button {
  display: inline-block;
  cursor: pointer;
  user-select: none;
}

phx-button[disabled] {
  cursor: not-allowed;
  opacity: 0.5;
}

phx-button[data-pressed="true"] {
  transform: scale(0.98);
  background-color: var(--phx-color-primary-active);
}
</style>

Attributes:

Attribute	Type	Default	Description
`disabled`	`boolean`	`false`	Disables the button

Events:

Event	Detail	Description
`phx-press-start`	-	Fired when press starts
`phx-press-end`	-	Fired when press ends
`phx-press`	-	Fired when press completes
`phx-press-cancel`	-	Fired when press is cancelled

phx-toggle (Toggle/Checkbox)

Handles toggle and checkbox state, supporting both binary and tri-state (indeterminate).

<!-- Basic checkbox -->
<phx-toggle id="checkbox1">
  Accept terms
</phx-toggle>

<!-- Pre-checked -->
<phx-toggle id="checkbox2" checked>
  Newsletter subscription
</phx-toggle>

<!-- Tri-state (indeterminate) -->
<phx-toggle id="checkbox3" allow-indeterminate>
  Select all items
</phx-toggle>

<script>
const toggle = document.getElementById('checkbox1');

// Events
toggle.addEventListener('phx-change', (e) => {
  console.log('Value:', e.detail.value); // true | false | 'indeterminate'
});

// API methods
toggle.toggle();           // Toggle between states
toggle.check();           // Set to true
toggle.uncheck();         // Set to false
toggle.setIndeterminate(); // Set to indeterminate (if allowIndeterminate)
toggle.reset();           // Reset to initial state

// Properties
toggle.value;             // true | false | 'indeterminate'
toggle.isChecked;         // boolean
toggle.isIndeterminate;   // boolean
</script>

<style>
phx-toggle {
  display: inline-block;
  cursor: pointer;
  user-select: none;
}

phx-toggle[disabled] {
  cursor: not-allowed;
  opacity: 0.5;
}

phx-toggle[data-checked="true"] .checkmark {
  background-color: var(--phx-color-primary);
}

phx-toggle[data-indeterminate="true"] .checkmark {
  background-color: var(--phx-color-neutral);
}
</style>

Attributes:

Attribute	Type	Default	Description
`checked`	`boolean`	`false`	Initial checked state
`indeterminate`	`boolean`	`false`	Initial indeterminate state
`allow-indeterminate`	`boolean`	`false`	Enable tri-state mode
`disabled`	`boolean`	`false`	Disables the toggle

Events:

Event	Detail	Description
`phx-change`	`{ value: boolean \| 'indeterminate' }`	Fired when value changes

phx-text-field (Text Field)

Handles text field state, validation, and formatting.

<!-- Basic usage -->
<phx-text-field id="name" required minlength="3">
  <input type="text" placeholder="Enter your name" />
</phx-text-field>

<!-- With validation -->
<phx-text-field 
  id="email" 
  required 
  pattern="[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$"
>
  <input type="email" placeholder="Enter your email" />
</phx-text-field>

<!-- With character limits -->
<phx-text-field id="bio" maxlength="500">
  <textarea placeholder="Tell us about yourself"></textarea>
</phx-text-field>

<script>
const field = document.getElementById('name');

// Events
field.addEventListener('phx-focus', (e) => {
  console.log('Field focused');
});

field.addEventListener('phx-blur', (e) => {
  console.log('Field blurred, value:', e.detail.value);
});

field.addEventListener('phx-input', (e) => {
  console.log('Input:', e.detail.value);
});

field.addEventListener('phx-invalid', (e) => {
  console.log('Invalid:', e.detail.message);
});

// API methods
field.validate();         // Returns boolean
field.reset();            // Reset to initial state
field.setValue('New value'); // Set value programmatically
field.getValue();         // Get current value

// Properties
field.isValid;            // boolean - is field valid
field.isDirty;            // boolean - has been changed
field.isVisited;          // boolean - has been focused and blurred
</script>

<style>
phx-text-field {
  display: block;
}

phx-text-field[data-valid="true"] input {
  border-color: var(--phx-color-success);
}

phx-text-field[data-valid="false"][data-visited="true"] input {
  border-color: var(--phx-color-error);
}
</style>

Attributes:

Attribute	Type	Default	Description
`disabled`	`boolean`	`false`	Disables the field
`required`	`boolean`	`false`	Makes field required
`pattern`	`string`	-	Regex pattern for validation
`minlength`	`number`	-	Minimum character length
`maxlength`	`number`	-	Maximum character length
`helper-id`	`string`	-	ID of helper text element
`error-id`	`string`	-	ID of error text element

Events:

Event	Detail	Description
`phx-focus`	-	Fired when field gains focus
`phx-blur`	`{ value }`	Fired when field loses focus
`phx-input`	`{ value }`	Fired on input change
`phx-invalid`	`{ value, message }`	Fired when validation fails
`phx-reset`	-	Fired when field is reset

phx-select (Select/Dropdown)

Handles select and dropdown interactions with single and multi-select support.

<!-- Basic select -->
<phx-select id="country" placeholder="Select a country">
  <phx-option value="us">United States</phx-option>
  <phx-option value="uk">United Kingdom</phx-option>
  <phx-option value="ca">Canada</phx-option>
</phx-select>

<!-- Multi-select -->
<phx-select id="skills" multiple searchable>
  <phx-option value="js">JavaScript</phx-option>
  <phx-option value="ts">TypeScript</phx-option>
  <phx-option value="react">React</phx-option>
</phx-select>

<script>
const select = document.getElementById('country');

// Events
select.addEventListener('phx-open', (e) => {
  console.log('Dropdown opened');
});

select.addEventListener('phx-close', (e) => {
  console.log('Dropdown closed');
});

select.addEventListener('phx-change', (e) => {
  console.log('Selected:', e.detail.selectedValues);
});

// API methods
select.open();            // Open dropdown
select.close();           // Close dropdown
select.selectItem('us');  // Select by value
select.deselectItem('us'); // Deselect by value
select.clearSelection();  // Clear all selections
select.reset();           // Reset to initial state

// Properties
select.isOpen;             // boolean - is dropdown open
select.selectedValues;     // string[] - selected values
select.highlightedIndex;   // number - highlighted option index

// Set items programmatically
select.setItems([
  { id: 'us', label: 'United States' },
  { id: 'uk', label: 'United Kingdom' },
]);
</script>

<style>
phx-select {
  display: block;
  position: relative;
}

phx-select[data-open="true"] {
  /* Open state styles */
}

phx-select[data-focused="true"] {
  /* Focused styles */
}
</style>

Attributes:

Attribute	Type	Default	Description
`disabled`	`boolean`	`false`	Disables the select
`multiple`	`boolean`	`false`	Enable multi-select
`searchable`	`boolean`	`false`	Enable search/filter
`placeholder`	`string`	-	Placeholder text

Events:

Event	Detail	Description
`phx-open`	-	Fired when dropdown opens
`phx-close`	-	Fired when dropdown closes
`phx-change`	`{ value, selectedValues }`	Fired when selection changes

phx-toast-container (Toast Notifications)

Manages toast notification lifecycle including queuing and dismissal.

<!-- Basic usage -->
<phx-toast-container id="toasts" position="bottom-right" max-visible="5">
</phx-toast-container>

<script>
const container = document.getElementById('toasts');

// Show toast
const toastId = container.show({
  message: 'Operation successful!',
  variant: 'success',
  title: 'Success',
  dismissible: true,
  duration: 5000,
});

// Convenience methods
container.success('Success message');
container.error('Error message');
container.warning('Warning message');
container.info('Info message');

// Dismiss toast
container.dismiss(toastId);

// Dismiss all
container.dismissAll();

// Set position
container.setPosition('top-right');

// Get visible toasts
container.getVisibleToasts();

// Check if has toasts
container.hasToasts();
</script>

<style>
phx-toast-container {
  position: fixed;
  z-index: 9999;
}

/* Position variants */
phx-toast-container[position="top-left"] { top: 0; left: 0; }
phx-toast-container[position="top-center"] { top: 0; left: 50%; transform: translateX(-50%); }
phx-toast-container[position="top-right"] { top: 0; right: 0; }
phx-toast-container[position="bottom-left"] { bottom: 0; left: 0; }
phx-toast-container[position="bottom-center"] { bottom: 0; left: 50%; transform: translateX(-50%); }
phx-toast-container[position="bottom-right"] { bottom: 0; right: 0; }

/* Toast variants */
.toast[data-variant="success"] { border-left: 4px solid var(--phx-color-success); }
.toast[data-variant="error"] { border-left: 4px solid var(--phx-color-error); }
.toast[data-variant="warning"] { border-left: 4px solid var(--phx-color-warning); }
.toast[data-variant="info"] { border-left: 4px solid var(--phx-color-info); }
</style>

Attributes:

Attribute	Type	Default	Description
`position`	`string`	`'bottom-right'`	Toast position
`max-visible`	`number`	`5`	Maximum visible toasts

Toast Options:

Option	Type	Default	Description
`message`	`string`	-	Toast message (required)
`variant`	`'success' \| 'error' \| 'warning' \| 'info' \| 'neutral'`	`'info'`	Toast type
`title`	`string`	-	Optional title
`duration`	`number`	`5000`	Duration in ms
`dismissible`	`boolean`	`true`	Allow dismissal
`pauseOnHover`	`boolean`	`true`	Pause on hover
`showProgress`	`boolean`	`false`	Show progress bar

JavaScript API

All elements support both attribute-based configuration and JavaScript API:

// Auto-registration (happens automatically on import)
import '@phoenix-tekhne/web-dynamis';

// Manual registration
import { 
  registerPhxButton,
  registerPhxToggle,
  registerPhxTextField,
  registerPhxSelect,
  registerPhxToastContainer,
  registerAllElements
} from '@phoenix-tekhne/web-dynamis';

// Register individually
registerPhxButton();

// Or register all at once
registerAllElements();

// Direct class access
import { PhxButtonElement } from '@phoenix-tekhne/web-dynamis';

class CustomButton extends PhxButtonElement {
  // Override methods
}

Styling with CSS Custom Properties

All elements use CSS custom properties for consistent styling:

/* Primary colors */
--phx-color-primary: #007bff;
--phx-color-success: #28a745;
--phx-color-error: #dc3545;
--phx-color-warning: #ffc107;
--phx-color-info: #17a2b8;

/* Spacing (8pt grid) */
--phx-spacing-100: 4px;
--phx-spacing-200: 8px;
--phx-spacing-300: 12px;
--phx-spacing-400: 16px;

/* Focus ring */
--phx-focus-ring: #4d90fe;

/* Border radius */
--phx-radius-md: 4px;

Greek Terminology

Greek	Transliteration	English	Used For
δύναμις	dynamis	Power, Ability	Core state machine package
προσκρούσις	proskrousis	Pressing against, striking	Button press interactions
κράσις	krasis	Mixing	Toggle/checkbox state
λέξις	lexis	Word	Text field validation
ἔλλειψις	epilipsis	Choice, selection	Select/dropdown
κήρυγμα	kerygma	Proclamation	Toast notifications

Related Packages

@phoenix-tekhne/dynamis-core - Pure TypeScript state machines
@phoenix-tekhne/react-dynamis - React hooks
@phoenix-tekhne/vue-dynamis - Vue 3 composables
@phoenix-tekhne/svelte-dynamis - Svelte stores
@phoenix-tekhne/angular-dynamis - Angular services

License

MIT

Dependencies

ID	Version
@phoenix-tekhne/dynamis-core	2.5.1

Development Dependencies

ID	Version
typescript	^5.7.0
vite	^6.0.0
vitest	^2.0.0

web-components custom-elements headless phoenix-tekhne dynamis

Details

npm

2026-05-28 07:22:40 -07:00

Phoenix Tekhne Team

MIT

latest

66 KiB

Assets (1)

web-dynamis-2.5.1.tgz 66 KiB

Versions (1) View all

2.5.1

2026-05-28

@phoenix-tekhne/web-dynamis (2.5.1)

Installation

About this package

@phoenix-tekhne/web-dynamis

Installation

Quick Start

Custom Elements

API Reference

phx-button (Press)

phx-toggle (Toggle/Checkbox)

phx-text-field (Text Field)

phx-select (Select/Dropdown)

phx-toast-container (Toast Notifications)

JavaScript API

Styling with CSS Custom Properties

Greek Terminology

Related Packages

License

Dependencies

Keywords