pns-component-library 1.5.13 → 1.6.0

package/README.md

@@ -4,7 +4,7 @@ A comprehensive Vue 3 component library built with modern development practices,
 
 ## 🚀 Features
 
-- **9 Production-Ready Components** - Form controls, layout components, and utility components
+- **11 Production-Ready Components** - Form controls, layout components, and utility components
 - **2 Powerful Composables** - Reusable logic for common patterns
 - **2 Custom Directives** - Loading states and UI enhancements
 - **Vue 3 Composition API** - Modern, performant, and type-safe
@@ -12,11 +12,32 @@ A comprehensive Vue 3 component library built with modern development practices,
 - **Accessibility** - ARIA attributes and keyboard navigation support
 - **Customizable Themes** - Multiple built-in color schemes
 
+> Newly released public components: `DropdownMenu`, `Badge`, `FloatingActionButton`, `DynamicColorResponsiveButton`.
+
+## 🆕 What's New
+
+### 2025-10-28
+
+- Public release of:
+  - `DropdownMenu`
+  - `Badge`
+  - `FloatingActionButton`
+  - `DynamicColorResponsiveButton`
+
+Import options:
+
+- Global (plugin):
+  - `app.use(PnsComponentLibrary)` then use components directly in templates.
+- Named import:
+  - `import { DropdownMenu, Badge, FloatingActionButton, DynamicColorResponsiveButton } from 'pns-component-library'`
+
 ## 📦 Installation
 
 ```bash
 npm install pns-component-library
 ```
+
+
 or
 
 ```bash
@@ -52,7 +73,15 @@ app.mount('#app')
     <!-- Phone input with country selection -->
     <AreaCodePhoneInput v-model="phoneData" />
     
-    <!-- Responsive button -->
+    <!-- Dynamic color responsive button (Recommended) -->
+    <DynamicColorResponsiveButton 
+      display_name="Click me" 
+      button_type="filled" 
+      built_in_theme="primary"
+      @click-button="handleClick"
+    />
+
+    <!-- Legacy button (Deprecated but still works; not maintained). New projects should migrate to DynamicColorResponsiveButton. -->
     <ResponsiveButton @click="handleClick">
       Click me
     </ResponsiveButton>
@@ -76,26 +105,37 @@ const handleClick = () => {
 ### Form Components
 
 #### AreaCodePhoneInput
-International phone number input with country selection and area code handling.
+International phone number input with country selection and area code handling. Features automatic country flag display, smart focus management, and a clear button that appears on hover/focus.
 
 ##### Attributes
 
 | Attribute | Description | Type | Default |
 |-----------|-------------|------|---------|
-| v-model / modelValue | binding value - object containing `area_code` (country code like "+1") and `phone_number` (local number) | `{area_code: string, phone_number: string}` | `{area_code: '', phone_number: ''}` |
-| country_options | custom country list | `array` | — |
-| enable_backup_country_options | use built-in country list | `boolean` | `true` |
-| country_filterable | enable country search | `boolean` | `true` |
+| v-model / modelValue | binding value - object containing `area_code` (string) and `phone_number` (string) | `{area_code: string, phone_number: string}` | `{}` |
+| country_options | custom country list with `country_name` and `country_code` properties | `Array<{country_name: string, country_code: string}>` | `[]` |
+| enable_backup_country_options | use built-in country list when no custom options provided | `boolean` | `true` |
+| country_filterable | enable country search/filtering in dropdown | `boolean` | `true` |
 | disabled | whether input is disabled | `boolean` | `false` |
 
 ##### Events
 
 | Event | Description | Parameters |
 |-------|-------------|------------|
-| change | triggers when the binding value changes | `(value: object)` |
-| focus | triggers when input is focused | `(event: FocusEvent)` |
-| blur | triggers when input is blurred | `(event: FocusEvent)` |
-| clear | triggers when clear button is clicked | — |
+| change | triggers when the binding value changes | `{area_code: string, phone_number: string}` |
+| focus | triggers when any part of the input gains focus | `{area_code: string, phone_number: string}` |
+| blur | triggers when the entire input loses focus | `{area_code: string, phone_number: string}` |
+| clear | triggers when clear button is clicked | `{area_code: string, phone_number: string}` |
+
+##### Exposes
+
+| Method | Description | Type |
+|--------|-------------|------|
+| focus | focus the appropriate input (country selector if no country selected, phone input if country selected) | `() => void` |
+| blur | blur both country selector and phone input | `() => void` |
+| clear | clear both country selection and phone number | `() => void` |
+| alert | show alert message below the input | `(message: string) => void` |
+| error | show error message below the input | `(message: string) => void` |
+| removeAlertOrErrorEffect | clear alert/error state and message | `() => void` |
 
 ```vue
 <template>
@@ -107,104 +147,197 @@ International phone number input with country selection and area code handling.
 </template>
 ```
 
+### Deprecated Components
+
+> Note: Deprecated components still work and are supported for backward compatibility, but they are no longer maintained. For new development, please migrate to the recommended replacements.
+
+#### ResponsiveButton (Deprecated, still works)
+Legacy feature-rich button component superseded by `DynamicColorResponsiveButton`.
+
+##### Attributes
+
+| Attribute | Description | Type | Default |
+|-----------|-------------|------|---------|
+| display_name | button text | `string` | `'button'` |
+| size | button size | `'xsmall' \| 'small' \| 'medium' \| 'large'` | `'small'` |
+| width_type | button width type | `'fill-whole' \| 'fit-content'` | `'fit-content'` |
+| build_in_theme | color theme | `'outlined-primary' \| 'filled-primary' \| 'text-primary' \| 'outlined-secondary' \| 'filled-secondary' \| 'text-secondary'` | `'outlined-primary'` |
+| customized_class | custom CSS class | `string` | — |
+| hold | whether button is in hold state | `boolean` | `false` |
+| disabled | whether button is disabled | `boolean` | `false` |
+| dropdown_options | dropdown menu options | `array` | `[]` |
+| is_dropdown_option | whether this is a dropdown item | `boolean` | `false` |
+
+##### Events
+
+| Event | Description | Parameters |
+|-------|-------------|------------|
+| click | triggers when button is clicked | `(event: MouseEvent)` |
+| update-currently-hovered-dropdown-option | triggers when dropdown option is hovered | `(option: object)` |
+| add-nested-dropdown-history-stack | triggers when nested dropdown is navigated | `(option: object)` |
+| remove-nested-dropdown-history-stack | triggers when navigating back in nested dropdown | — |
+
+##### Slots
+
+| Name | Description |
+|------|-------------|
+| prefix | content before button text |
+| suffix | content after button text |
+
+```vue
+<template>
+  <ResponsiveButton 
+    display_name="Save Changes"
+    size="medium"
+    build_in_theme="filled-primary"
+    @click="handleSave"
+  >
+    <template #prefix>
+      <img :src="iconsMap['eye_icon']" alt="eye" />
+    </template>
+  </ResponsiveButton>
+</template>
+```
+
 #### InputBox
-Versatile input field component with validation and styling options.
+Versatile input field with clearable icon, inside/outside label, styled themes, and validation helpers. The component dynamically adjusts border/background/label colors based on state (hover, focus, disabled, alert, error) and supports prefix/suffix slots.
 
 ##### Attributes
 
 | Attribute | Description | Type | Default |
 |-----------|-------------|------|---------|
-| v-model / modelValue | binding value - the current input text value | `string` | — |
-| type | input type | `string` | `'text'` |
+| v-model / modelValue | bound input value | `string` | `''` |
+| label | label text (optional) | `string` | `''` |
+| label_type | where to render the label | `'inside' \| 'outside'` | `'outside'` |
+| theme_type | visual styling theme | `'filled' \| 'outlined'` | `'outlined'` |
+| customized_theme_color | focus/brand color used for focus border or underline; any valid CSS color or CSS var | `string` | `''` |
+| type | native input type | `string` | `'text'` |
 | placeholder | placeholder text | `string` | `'Enter'` |
-| clearable | whether to show clear button | `boolean` | `false` |
-| disabled | whether input is disabled | `boolean` | `false` |
-| autocomplete | autocomplete attribute for input, raw input tag values work | `string` | `'off'` |
+| clearable | show a clear icon when focused/hovered and value is non-empty | `boolean` | `false` |
+| required | show a required asterisk on the label. Visual-only; does not enforce validation | `boolean` | `false` |
+| disabled | disable the input | `boolean` | `false` |
+| autocomplete | native `autocomplete` | `string` | `'off'` |
+
+Behavior notes:
+
+- In `filled` theme, a bottom inset shadow emulates the underline. In `outlined` theme, an inset border is used. Colors are derived from:
+  - Focus: `customized_theme_color` (or `var(--Schemes-primary)` fallback)
+  - Hover: `#17181C`
+  - Disabled: `var(--disabled-color--)` and `var(--disabled-button-background-color--)`
+  - Alert/Error: `var(--semantic-alert-color--)` / `var(--semantic-error-color--)`
+- Inside label floats above the input content area and inherits a state color similar to the border color.
+- A message region appears below the field when either `#supportingText` slot has content or when alert/error is active with a message.
+- `#supportingText` is neutral and does not adopt alert/error colors; alert/error messages are colored separately.
+- Alert/Error messages are set via exposes: `alert(message)` / `error(message)`; call `removeAlertOrErrorEffect()` to clear.
+- Disabled state down-weights message colors.
 
 ##### Events
 
 | Event | Description | Parameters |
 |-------|-------------|------------|
-| input | triggers when input value changes | `(value: string)` |
-| change | triggers when input value changes and loses focus | `(value: string)` |
-| focus | triggers when input is focused | `(event: FocusEvent)` |
-| blur | triggers when input is blurred | `(event: FocusEvent)` |
-| clear | triggers when clear button is clicked | — |
+| input | fires on each keystroke | `(value: string)` |
+| change | fires on Enter or blur | `(value: string)` |
+| focus | input focused | `()` |
+| blur | input blurred | `()` |
+| clear | clear button clicked | `()` |
 
 ##### Exposes
 
-| Method | Description | Type |
-|--------|-------------|------|
-| focus | focus the input | `() => void` |
-| blur | blur the input | `() => void` |
-| alert | show alert message | `(message: string) => void` |
-| error | show error message | `(message: string) => void` |
-| removeAlertOrErrorEffect | clear alert/error state | `() => void` |
+| Method | Description |
+|--------|-------------|
+| focus | programmatically focus the input |
+| blur | programmatically blur the input |
+| alert | show alert state with a message (yellow) |
+| error | show error state with a message (red) |
+| removeAlertOrErrorEffect | clear alert/error state |
 
 ##### Slots
 
 | Name | Description |
 |------|-------------|
-| prefix | content before input |
-| suffix | content after input |
+| prefix | content rendered before the input (e.g., an icon) |
+| suffix | content rendered after the input (e.g., an icon) |
+| supportingText | optional helper text rendered below the field (e.g., character counter like `0/100`). This is distinct from alert/error messages and uses a neutral color. When alert/error is active, their messages render alongside (with their own colors) |
+
+> Tip: For prefix/suffix icons, prefer inline SVG that uses `fill="currentColor"`. This way the icon color automatically follows the component state (hover/focus/disabled/alert/error). If you use `<img>` sources, they won't inherit color.
+
+##### Usage
 
 ```vue
-<InputBox 
-  v-model="value" 
-  type="text" 
-  placeholder="Enter text" 
-  clearable
->
-  <template #prefix>
-    <Icon name="search" />
-  </template>
-</InputBox>
-```
+<template>
+  <InputBox
+    v-model="value"
+    label="Email"
+    label_type="inside"
+    theme_type="outlined"
+    customized_theme_color="var(--Schemes-primary)"
+    type="email"
+    placeholder="name@example.com"
+    clearable
+    autocomplete="email"
+  >
+    <template #prefix>
+      <img src="/icons/mail.svg" style="width:100%;height:100%"/>
+    </template>
+  </InputBox>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+const value = ref('')
+</script>
 
 #### SingleSelector
-Dropdown selector component with filtering and search capabilities.
+Dropdown selector with inside/outside label, themed styling, filtering, and optional remote search. Mirrors `InputBox` visual behavior (hover/focus/disabled/alert/error), and supports prefix/suffix slots plus a neutral `supportingText` message region.
 
 ##### Attributes
 
 | Attribute | Description | Type | Default |
 |-----------|-------------|------|---------|
-| v-model / modelValue | binding value - the `value` property of the selected option from the options array | `string \| number \| boolean \| object \| array` | — |
-| options | options array | `Array<{value: any, label: string}>` | `[]` |
-| filterable | whether to enable filtering | `boolean` | `false` |
-| remote_search | whether to enable remote search | `boolean` | `false` |
-| disabled | whether selector is disabled | `boolean` | `false` |
-| placeholder | placeholder text | `string` | `'Select'` |
-| clearable | whether to show clear button | `boolean` | `false` |
-| loading | loading state | `boolean` | `false` |
+| v-model / modelValue | binding value (selected option's `value`) | `string \| number \| boolean \| object \| array` |
+| label | label text | `string` | `''` |
+| label_type | label position | `'inside' \| 'outside'` | `'outside'` |
+| theme_type | visual theme | `'filled' \| 'outlined'` | `'outlined'` |
+| customized_theme_color | focus/brand color; any CSS color or CSS var | `string` | `''` |
+| required | show red asterisk next to label | `boolean` | `false` |
+| options | options array | `Array<{ value: string \| number \| boolean \| object, label: string, prefix?: string, suffix?: string, prefix_slot_raw_html_content?: string, suffix_slot_raw_html_content?: string, options?: Option[], has_divider?: boolean, disabled?: boolean, is_selected?: boolean }>` | `[]` |
+| filterable | enable client-side filter input | `boolean` | `false` |
+| remote_search | emit query outward instead of local filtering | `boolean` | `false` |
+| disabled | disable selector | `boolean` | `false` |
+| placeholder | placeholder when no value | `string` | `'Select'` |
+| clearable | show clear icon when there is a value and focused/hovered | `boolean` | `false` |
+| loading | loading state (mirrors dropdown's `is_loading`) | `boolean` | `false` |
 | loading_text | loading text | `string` | `'Loading'` |
-| no_data_text | no data text | `string` | `'No data'` |
-| filter_only_among_options_value | filter only among option values | `boolean` | `false` |
-| filter_only_among_options_label | filter only among option labels | `boolean` | `false` |
+| no_data_text | empty-state text | `string` | `'No data'` |
+| filter_only_among_options_value | filter against serialized `value` only | `boolean` | `false` |
+| filter_only_among_options_label | filter against `label` only | `boolean` | `false` |
+
+Notes:
 
-> **Note**: `filter_only_among_options_value` and `filter_only_among_options_label` cannot be true at the same time. If both are true, `filter_only_among_options_value=true` will override `filter_only_among_options_label`'s logic.
+- `filter_only_among_options_value` and `filter_only_among_options_label` cannot both be `true`. If both are `true`, filtering uses `value`.
+- Option `value` may be primitive or object; selection compares by `value` plus `label` for marking `is_selected` in lists.
 
 ##### Events
 
 | Event | Description | Parameters |
 |-------|-------------|------------|
 | change | triggers when the binding value changes | `(value: any)` |
-| remote-search | triggers when remote search is performed | `(query: string)` |
-| filter-change | triggers when filter text changes | `(query: string)` |
-| visible-change | triggers when dropdown visibility changes | `(visible: boolean)` |
-| focus | triggers when selector is focused | `(event: FocusEvent)` |
-| blur | triggers when selector is blurred | `(event: FocusEvent)` |
-| clear | triggers when clear button is clicked | — |
+| remote-search | triggers when `remote_search=true` and user types | `(query: string)` |
+| filter-change | triggers whenever filter text changes | `(query: string)` |
+| visible-change | dropdown visibility changes | `(visible: boolean)` |
+| focus | selector focused | `()` |
+| blur | selector blurred | `()` |
+| clear | clear button clicked | `()` |
 
 ##### Exposes
 
-| Method | Description | Type |
-|--------|-------------|------|
-| focus | focus the selector | `() => void` |
-| blur | blur the selector | `() => void` |
-| alert | show alert message | `(message: string) => void` |
-| error | show error message | `(message: string) => void` |
-| removeAlertOrErrorEffect | clear alert/error state | `() => void` |
-| setDropdownContentLoading | set loading state | `(loading: boolean) => void` |
+| Method | Description |
+|--------|-------------|
+| focus | programmatically focus the selector |
+| blur | programmatically blur the selector |
+| alert | show alert state with a message (yellow) |
+| error | show error state with a message (red) |
+| removeAlertOrErrorEffect | clear alert/error state |
 
 ##### Slots
 
@@ -212,11 +345,13 @@ Dropdown selector component with filtering and search capabilities.
 |------|-------------|
 | prefix | content before selector |
 | suffix | content after selector |
+| supportingText | neutral helper text under the field; alert/error messages render alongside in their own colors |
 
 ```vue
 <SingleSelector 
   v-model="selected"
   :options="options"
+{{ ... }}
   filterable
   clearable
   placeholder="Choose option"
@@ -224,9 +359,25 @@ Dropdown selector component with filtering and search capabilities.
   <template #prefix>
     <Icon name="search" />
   </template>
+  <template #supportingText>
+    <!-- e.g. instruction or character counter; neutral color -->
+    Pick one option
+  </template>
 </SingleSelector>
 ```
 
+##### DropdownMenu (dev-only)
+
+Used internally by components to render options lists.
+
+- Props: `width_type: 'fill-whole'|'fit-content'`, `options` (same schema as above), `size: 'small'|'medium'|'large'`, `with_box_shadow`, `is_loading`, `loading_text`, `no_data_text`.
+- Events:
+  - `select-dropdown-option(value, label, in_dropdown_level)`
+  - `add-new-shown-nested-dropdown(target_item_props, trigger)`
+  - `remove-shown-nested-dropdown(target_item_props)`
+  - `update-shown-nested-dropdown(target_item_props)`
+  - `click-outside-dropdown-menu(event)`
+
 #### Checkbox
 Customizable checkbox with multiple themes and validation support.
 
@@ -237,7 +388,8 @@ Customizable checkbox with multiple themes and validation support.
 | v-model / modelValue | binding value - `true` when checked, `false` when unchecked | `boolean` | `false` |
 | label | checkbox label | `string` | — |
 | size | checkbox size | `'small' \| 'medium'` | `'medium'` |
-| built_in_theme | color theme | `'green' \| 'primary-blue' \| 'secondary-blue' \| 'red'` | `'green'` |
+| built_in_theme | built-in color theme | `'green' \| 'primary-blue' \| 'secondary-blue'` | `'green'` |
+| customized_theme_color | custom theme color (overrides built_in_theme) | `string`（any valid CSS color value） | `''` |
 | customized_class | custom CSS class | `string` | — |
 | disabled | whether checkbox is disabled | `boolean` | `false` |
 | autofocus | whether to auto focus | `boolean` | `false` |
@@ -255,15 +407,31 @@ Customizable checkbox with multiple themes and validation support.
 |--------|-------------|------|
 | focus | focus the checkbox | `() => void` |
 | blur | blur the checkbox | `() => void` |
-| alert | show error message | `(message: string) => void` |
+| error | show error message, will automatically use the error theme | `(message: string) => void` |
 | removeAlertOrErrorEffect | clear error state | `() => void` |
 
 ```vue
 <template>
+  <!-- the #FF0000 will override the built-in theme color -->
   <Checkbox 
     v-model="agreed" 
     label="I agree to terms" 
     built_in_theme="primary-blue"
+    customized_theme_color="#FF0000"
+    @change="handleChange"
+  />
+  <!-- if want to use global defined color as the theme color, can use var() -->
+  <Checkbox 
+    v-model="agreed" 
+    label="I agree to terms" 
+    customized_theme_color="var(--Schemes-primary)"
+    @change="handleChange"
+  />
+  <!-- Theme color can be any form of CSS color value. Since if the theme color isn't empty, it will override the built-in theme color. The background color of the checked and indeterminate state, and the mask color of the interaction effects of the checkbox will be the theme color, while the border color of unchecked checkbox will always be hsl(226, 8%, 10%). But when the checkbox is in error state, the theme will be error theme (the border color of unchecked checkbox, the background color of the checked and indeterminate state, and the mask color of the interaction effects of the checkbox will always be --semantic-error-color--) -->
+  <Checkbox 
+    v-model="agreed" 
+    label="I agree to terms" 
+    customized_theme_color="hsl(3, 71%, 40%)"
     @change="handleChange"
   />
 </template>
@@ -295,7 +463,85 @@ Container for managing multiple related checkboxes as a group.
 const selectedItems = ref(['option1'])
 const options = ['option1', 'option2', 'option3']
 </script>
+
+#### DropdownMenu
+Public dropdown menu primitive with nested dropdown support and responsive behavior (web vs. mobile). The companion `DropdownMenuItem` remains internal and is not exposed publically.
+
+##### Attributes
+
+| Attribute | Description | Type | Default |
+|-----------|-------------|------|---------|
+| options | menu options tree (see schema below) | `Array<Option>` | `[]` |
+| size | menu item sizing | `'small' \| 'medium' \| 'large'` | `'small'` |
+| width_type | width behavior | `'fill-whole' \| 'fit-content'` | `'fill-whole'` |
+| with_box_shadow | whether the menu container has a shadow | `boolean` | `true` |
+
+Option schema (recursive):
+
 ```
+type Option = {
+  value: string,
+  label: string,
+  // Optional visuals (priority: slot > raw HTML > image URL handled inside items)
+  prefix?: string,
+  suffix?: string,
+  prefix_slot_raw_html_content?: string,
+  suffix_slot_raw_html_content?: string,
+  // Nesting
+  options?: Option[],
+  // Visual divider hint for the following item
+  has_divider?: boolean,
+  // Disabled state
+  disabled?: boolean,
+}
+```
+
+Behavior notes:
+
+- On wide screens (width > 1024), nested dropdowns open as side menus on hover/click with smart positioning.
+- On small screens (≤ 1024), a single column flow is used; nested levels replace the list view using an internal history stack and a back affordance.
+- The component emits a click-outside event when the user clicks outside of the root dropdown.
+
+##### Events
+
+| Event | Description | Parameters |
+|-------|-------------|------------|
+| select-dropdown-option | emitted when an option without further nesting is selected | `(value: string, in_dropdown_level: number)` |
+| click-outside-dropdown-menu | emitted when clicking outside the root menu | `—` |
+
+##### Usage
+
+```vue
+<template>
+  <DropdownMenu
+    :options="options"
+    :size="'small'"
+    :width_type="'fill-whole'"
+    @click-outside-dropdown-menu="onOutside"
+    @select-dropdown-option="onSelect"
+  />
+</template>
+
+<script setup>
+import { DropdownMenu } from 'pns-component-library'
+
+const options = [
+  {
+    value: 'option1',
+    label: 'Option 1',
+    options: [
+      { value: 'option1.1', label: 'Option 1.1' },
+      { value: 'option1.2', label: 'Option 1.2', options: [
+        { value: 'option1.2.1', label: 'Option 1.2.1' },
+      ]},
+    ],
+  },
+  { value: 'option2', label: 'Option 2' },
+]
+
+function onOutside(){ /* handle outside click */ }
+function onSelect(value, level){ /* handle select */ }
+</script>
 
 #### Radio
 Radio button component for single selection from multiple options.
@@ -338,56 +584,249 @@ Radio button component for single selection from multiple options.
 <Radio v-model="single" value="yes" label="Agree to terms" />
 ```
 
+#### Badge
+Notification badge component with customizable size, position, themes, and content display. Features automatic text color calculation for optimal contrast.
+
+##### Attributes
+
+| Attribute | Description | Type | Default |
+|-----------|-------------|------|---------|
+| content | badge content (number or text) | `string \| number` | `''` |
+| size | badge size | `'small' \| 'medium' \| 'large'` | `'small'` |
+| position_type | badge position relative to content | `'top-right' \| 'center-right'` | `'top-right'` |
+| built_in_theme | color theme | `'primary' \| 'secondary'` | `'primary'` |
+| customized_theme_color | custom background color (any valid CSS color) | `string` | `''` |
+| customized_class | custom CSS class | `string` | `''` |
+
+##### Size Specifications
+
+| Size | Web (px) | Mobile ≤767px (px) | With Content |
+|------|----------|-------------------|--------------|
+| small | 6×6 | 6×6 | auto-sized |
+| medium | 8×8 | 6×6 | auto-sized |
+| large | 16×16 | 16×16 | auto-sized |
+
+> **Note**: When badge has content, it automatically becomes large with padding (min-width: 20px, height: 20px).
+
+##### Position Types
+
+| Position | Behavior |
+|----------|----------|
+| top-right | Positioned absolutely at top-right corner (0, 0) |
+| center-right | Inline-flex aligned at right side with 4px gap |
+
+> **Note**: Use padding on the wrapper div to control badge position. The badge positions relative to the wrapper's content.
+
+##### Built-in Themes
+
+| Theme | Background | Text Color |
+|-------|-----------|------------|
+| primary | #AF251D (red) | #FFFFFF (white) |
+| secondary | #CFE0FC (light blue) | #083D91 (dark blue) |
+
+##### Custom Theme Color
+
+When using `customized_theme_color`, the text color is automatically calculated based on the background lightness:
+- Light backgrounds (lightness > 50%) → dark text
+- Dark backgrounds (lightness ≤ 50%) → light text
+
+The algorithm adjusts lightness by ±60 while preserving hue and saturation for optimal contrast and color harmony.
+
+```vue
+<template>
+  <!-- Basic badge with sizes -->
+  <Badge size="small">
+    <div style="padding: 4px;">
+      <div>Icon</div>
+    </div>
+  </Badge>
+
+  <!-- Badge with content -->
+  <Badge content="5">
+    <div style="padding: 8px;">
+      <div>Icon</div>
+    </div>
+  </Badge>
+
+  <!-- Badge with position types -->
+  <Badge position_type="top-right" content="3">
+    <div style="padding: 8px;">
+      <div>Icon</div>
+    </div>
+  </Badge>
+
+  <!-- Badge with custom color -->
+  <Badge customized_theme_color="#10B981" content="New">
+    <div style="padding: 8px;">
+      <div>Icon</div>
+    </div>
+  </Badge>
+
+  <!-- Dark background example -->
+  <Badge customized_theme_color="hsl(220, 70%, 25%)" content="Dark">
+    <div style="padding: 8px;">
+      <div>Icon</div>
+    </div>
+  </Badge>
+</template>
+```
+
 ### Interactive Components
 
-#### ResponsiveButton
-Feature-rich button component with responsive behavior and multiple states.
+#### DynamicColorResponsiveButton
+Modern button with dynamic color logic and responsive behavior.
+
+##### Attributes
+
+| Attribute | Description | Type | Default |
+|-----------|-------------|------|---------|
+| button_type | button style variant | `'filled' \| 'outlined' \| 'text' \| 'elevated'` | `'filled'` |
+| button_border_radius | CSS border-radius value | `string` | `'100px'` |
+| built_in_theme | built-in color theme | `'primary' \| 'secondary' \| 'tertiary' \| 'primary-container' \| 'secondary-container' \| 'tertiary-container'` | `'primary'` |
+| customized_theme_color | overrides built_in_theme with any CSS color (e.g., `#3d5c8f`, `rgb(...)`, `hsl(...)`, `var(--Schemes-primary)`) | `string` | `''` |
+| customized_class | custom CSS class for outer container | `string` | `''` |
+| width_type | width mode | `'fill-whole' \| 'fit-content'` (auto-handles icon-only with `narrow`/`wide`) | `'fit-content'` |
+| button_id | explicit id used in emitted event; falls back to `display_name` | `string` | `''` |
+| display_name | button text (used when default slot empty) | `string` | `'button name'` |
+| prefix | image url for prefix when not using slot | `string` | `''` |
+| suffix | image url for suffix when not using slot | `string` | `''` |
+| prefix_slot_raw_html_content | raw html for prefix (when not using named slot) | `string` | `''` |
+| suffix_slot_raw_html_content | raw html for suffix (when not using named slot) | `string` | `''` |
+| disabled | disable interaction | `boolean` | `false` |
+| has_interaction_effect | enable hover/focus/active visual effects (mask and slight radius changes). Set to `false` to keep the button static (useful when embedding purely for coloring icons/slots) | `boolean` | `true` |
+| size | size (Web/Tablet enum) | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'small'` |
+
+##### Events
+
+| Event | Description | Parameters |
+|-------|-------------|------------|
+| click-button | emitted on button click | `(button_id: string, display_name: string)` |
+
+##### Exposes
+
+| Method | Description | Type |
+|--------|-------------|------|
+| handleFocusButton | programmatically apply focus style | `() => void` |
+| handleBlurButton | remove focus style | `() => void` |
+
+##### Slots
+
+| Name | Description |
+|------|-------------|
+| prefix | content before the label (e.g., icon) |
+| default | label content; falls back to `display_name` |
+| suffix | content after the label (e.g., icon) |
+
+```vue
+<template>
+  <DynamicColorResponsiveButton 
+    button_id="save-changes"
+    display_name="Save Changes"
+    button_type="filled"
+    built_in_theme="primary"
+    :has_interaction_effect="true"
+    width_type="fit-content"
+    @click-button="onSave"
+  >
+    <template #prefix>
+      <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="currentColor"><path d="M5 12h14v2H5z"/></svg>
+    </template>
+  </DynamicColorResponsiveButton>
+</template>
+
+<script setup>
+function onSave(id, name){
+  console.log('clicked:', id, name)
+}
+</script>
+```
+
+#### FloatingActionButton
+Mobile-only floating action button that anchors to the bottom-right of the viewport on small screens. It supports three sizes, built-in themes or a custom theme color, named slots for icons, and an optional one-level options menu. The button is automatically hidden on wide screens (when `window.width > 1024`).
 
 ##### Attributes
 
 | Attribute | Description | Type | Default |
 |-----------|-------------|------|---------|
 | display_name | button text | `string` | `'button'` |
-| size | button size | `'xsmall' \| 'small' \| 'medium' \| 'large'` | `'small'` |
-| width_type | button width type | `'fill-whole' \| 'fit-content'` | `'fit-content'` |
-| build_in_theme | color theme | `'outlined-primary' \| 'filled-primary' \| 'text-primary' \| 'outlined-secondary' \| 'filled-secondary' \| 'text-secondary'` | `'outlined-primary'` |
-| customized_class | custom CSS class | `string` | — |
-| hold | whether button is in hold state | `boolean` | `false` |
-| disabled | whether button is disabled | `boolean` | `false` |
-| dropdown_options | dropdown menu options | `array` | `[]` |
-| is_dropdown_option | whether this is a dropdown item | `boolean` | `false` |
+| size | button size | `'small' \| 'medium' \| 'large'` | `'small'` |
+| build_in_theme | built-in color theme | `'primary' \| 'secondary' \| 'tertiary' \| 'primary-container' \| 'secondary-container' \| 'tertiary-container'` | `'primary'` |
+| customized_theme_color | custom theme color (overrides built_in_theme). Accepts any valid CSS color string (e.g., `#3d5c8f`, `rgb(61, 92, 143)`, `hsl(217, 40%, 40%)`, or `var(--Schemes-primary)`). | `string` | `''` |
+| customized_class | custom CSS class for the outer container | `string` | `''` |
+| options | optional menu options (one level). Each item is `{ value: any, label: string, prefix?: string, suffix?: string }`. `prefix`/`suffix` are icon URLs for the option. | `array` | `[]` |
+
+> Notes
+> - When `options` is non-empty, clicking the FAB toggles the options menu. A cross button is provided to close the menu.
+> - The component is hidden on wide screens (`width > 1024`) by design to target mobile usage.
+> - `customized_theme_color` overrides `build_in_theme`. If it is not provided (empty string), the `build_in_theme` color will be used instead.
+> - `customized_theme_color` accepts any valid CSS color value: e.g. `hsl(217, 40%, 40%)`, `#ff0000`, `rgb(255, 0, 0)`, `rgba(255, 0, 0, 0.5)`, `hsla(217, 40%, 40%, 0.5)`, or `var(--Schemes-primary)`.
+> - When using `customized_theme_color`:
+>   - The FAB background color uses the provided value directly.
+>   - Related colors (text color, inline SVG color via currentColor, menu cross button colors, menu child button colors, and interaction masks) are dynamically calculated based on the `customized_theme_color` to ensure contrast and visual harmony.
 
 ##### Events
 
 | Event | Description | Parameters |
 |-------|-------------|------------|
-| click | triggers when button is clicked | `(event: MouseEvent)` |
-| update-currently-hovered-dropdown-option | triggers when dropdown option is hovered | `(option: object)` |
-| add-nested-dropdown-history-stack | triggers when nested dropdown is navigated | `(option: object)` |
-| remove-nested-dropdown-history-stack | triggers when navigating back in nested dropdown | — |
+| floating-action-button-click | emitted when the floating action button is clicked. If `options` is provided, this also toggles the menu visibility. | — |
+| option-click | emitted when a menu option is clicked | `(value: any)` |
 
 ##### Slots
 
 | Name | Description |
 |------|-------------|
-| prefix | content before button text |
-| suffix | content after button text |
+| prefix | content rendered before the button text. Commonly used for an icon. |
+| default | default slot for button label content. Falls back to `display_name` when empty. |
+| suffix | content rendered after the button text. Commonly used for an icon. |
 
 ```vue
 <script setup>
-import { iconsMap } from 'pns-component-library';
+const quickCreateOptions = [
+  { value: 'photo', label: 'New Photo' },
+  { value: 'video', label: 'New Video' },
+  { value: 'doc', label: 'New Doc' },
+]
+
+const handleFabClick = () => {
+  console.log('FAB clicked')
+}
+
+const handleOptionClick = (val) => {
+  console.log('Option clicked:', val)
+}
 </script>
+
 <template>
-  <ResponsiveButton 
-    display_name="Save Changes"
-    size="medium"
-    build_in_theme="filled-primary"
-    @click="handleSave"
+  <!-- Will only be visible on small screens (hidden on width > 1024) -->
+  <FloatingActionButton
+    display_name="New"
+    size="small"
+    build_in_theme="tertiary"
+    :options="quickCreateOptions"
+    @floating-action-button-click="handleFabClick"
+    @option-click="handleOptionClick"
   >
     <template #prefix>
-      <img :src="iconsMap['eye_icon']" alt="eye" />
+      <!-- Example icon (uses currentColor to adapt) -->
+      <!-- Pros of using inline SVG:
+           - Inherits currentColor automatically, so it adapts to theme/text color without extra CSS
+           - Reacts naturally to hover/active color-mix effects used by the component
+           - No additional network request for external assets
+         Using a regular <img src="..."> is also fine if you prefer image assets;
+         just note that <img> won't inherit currentColor by default (you'd need pre-colored assets or additional CSS). -->
+      <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none">
+        <path d="M6 16L10 12.95L14 16L12.5 11.05L16.5 8.2H11.6L10 3L8.4 8.2H3.5L7.5 11.05L6 16ZM10 20C8.61667 20 7.31667 19.7375 6.1 19.2125C4.88333 18.6875 3.825 17.975 2.925 17.075C2.025 16.175 1.3125 15.1167 0.7875 13.9C0.2625 12.6833 0 11.3833 0 10C0 8.61667 0.2625 7.31667 0.7875 6.1C1.3125 4.88333 2.025 3.825 2.925 2.925C3.825 2.025 4.88333 1.3125 6.1 0.7875C7.31667 0.2625 8.61667 0 10 0C11.3833 0 12.6833 0.2625 13.9 0.7875C15.1167 1.3125 16.175 2.025 17.075 2.925C17.975 3.825 18.6875 4.88333 19.2125 6.1C19.7375 7.31667 20 8.61667 20 10C20 11.3833 19.7375 12.6833 19.2125 13.9C18.6875 15.1167 17.975 16.175 17.075 17.075C16.175 17.975 15.1167 18.6875 13.9 19.2125C12.6833 19.7375 11.3833 20 10 20Z" fill="currentColor"/>
+      </svg>
     </template>
-  </ResponsiveButton>
+  </FloatingActionButton>
+
+  <!-- Custom theme color overrides built-in theme -->
+  <FloatingActionButton
+    display_name="Custom"
+    size="medium"
+    customized_theme_color="hsl(217, 40%, 40%)"
+    @floating-action-button-click="handleFabClick"
+  />
 </template>
 ```
 
@@ -588,7 +1027,7 @@ The library provides multiple built-in themes:
 
 ```vue
 <Checkbox built_in_theme="primary-blue" />
-<ResponsiveButton built_in_theme="outlined-primary" />
+<DynamicColorResponsiveButton button_type="filled" built_in_theme="primary" />
 ```
 
 ## 📱 Responsive Design