@umbra.ui/core 0.1.17 → 0.1.19

package/dist/components/controls/Dropdown/README.md

@@ -0,0 +1,370 @@
+# Dropdown
+
+A fully-featured dropdown component built with Vue 3 Composition API and TypeScript. The Dropdown component provides a customizable select interface with keyboard navigation, accessibility features, and smooth animations.
+
+## Installation/Import
+
+```typescript
+import { Dropdown } from "@umbra-ui/core";
+import type { DropdownItem } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for chevron icon)
+- @umbra-ui/core (Button component)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Dropdown } from "@umbra-ui/core";
+import type { DropdownItem } from "@umbra-ui/core";
+
+const selectedItem = ref<DropdownItem | null>(null);
+
+const dropdownItems: DropdownItem[] = [
+  { id: "1", title: "Option 1" },
+  { id: "2", title: "Option 2" },
+  { id: "3", title: "Option 3" },
+];
+
+const handleSelectionChange = (item: DropdownItem | null) => {
+  console.log("Selected item:", item);
+  selectedItem.value = item;
+};
+</script>
+
+<template>
+  <Dropdown
+    :items="dropdownItems"
+    v-model="selectedItem"
+    placeholder="Choose an option"
+    @change="handleSelectionChange"
+  />
+</template>
+```
+
+## Props
+
+| Prop Name     | Type                   | Required | Default                                                                               | Description                                  |
+| ------------- | ---------------------- | -------- | ------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `items`       | `DropdownItem[]`       | Yes      | `[{ id: "1", title: "One" }, { id: "2", title: "Two" }, { id: "3", title: "Three" }]` | Array of dropdown items to display           |
+| `modelValue`  | `DropdownItem \| null` | No       | `null`                                                                                | Currently selected item (v-model support)    |
+| `showOverlay` | `boolean`              | No       | `true`                                                                                | Whether to show background overlay when open |
+| `placeholder` | `string`               | No       | `"Select an option"`                                                                  | Placeholder text when no item is selected    |
+
+### DropdownItem Interface
+
+```typescript
+interface DropdownItem {
+  id: string | number;
+  title: string;
+  subtitle?: string;
+  disabled?: boolean;
+}
+```
+
+## Events
+
+| Event Name          | Payload Type           | Description                                 |
+| ------------------- | ---------------------- | ------------------------------------------- |
+| `update:modelValue` | `DropdownItem \| null` | Emitted when selection changes (v-model)    |
+| `change`            | `DropdownItem \| null` | Emitted when selection changes (additional) |
+
+### Event Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Dropdown } from "@umbra-ui/core";
+import type { DropdownItem } from "@umbra-ui/core";
+
+const selectedItem = ref<DropdownItem | null>(null);
+
+const handleModelValueUpdate = (item: DropdownItem | null) => {
+  console.log("Model value updated:", item);
+  selectedItem.value = item;
+};
+
+const handleChange = (item: DropdownItem | null) => {
+  console.log("Selection changed:", item);
+};
+</script>
+
+<template>
+  <Dropdown
+    :items="dropdownItems"
+    v-model="selectedItem"
+    @update:model-value="handleModelValueUpdate"
+    @change="handleChange"
+  />
+</template>
+```
+
+## Slots
+
+This component does not use slots. All content is controlled via props.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs via `defineExpose`.
+
+## CSS Customization
+
+The Dropdown component uses CSS custom properties that can be overridden to customize the appearance:
+
+### Color Variables
+
+```css
+/* Dropdown popover colors */
+--dropdown-popover-bg: #ffffff;
+--dropdown-popover-border: 1px solid rgba(0, 0, 0, 0.1);
+--dropdown-shadow-dark: transparent;
+--dropdown-shadow-light: rgba(255, 255, 255, 0.7);
+
+/* Dropdown item colors */
+--dropdown-item-border: rgba(0, 0, 0, 0.08);
+--dropdown-item-hover-bg: #f0f2f4;
+--dropdown-item-focused-bg: rgba(0, 0, 0, 0.04);
+--dropdown-item-selected-bg: rgba(0, 144, 255, 0.1);
+--dropdown-item-selected-hover-bg: rgba(0, 144, 255, 0.15);
+--dropdown-item-subtitle: #60646c;
+
+/* Icon colors */
+--dropdown-icon-color: #1a1d23;
+--dropdown-icon-color-default: #1a1d23;
+--dropdown-icon-color-secondary: #60646c;
+
+/* Overlay color */
+--dropdown-overlay-bg: rgba(0, 0, 0, 0.1);
+```
+
+### Custom Styling Example
+
+```vue
+<template>
+  <Dropdown :items="items" v-model="selectedItem" class="custom-dropdown" />
+</template>
+
+<style>
+.custom-dropdown {
+  --dropdown-item-selected-bg: #ff6b6b;
+  --dropdown-item-selected-hover-bg: #ff5252;
+  --dropdown-popover-bg: #f8f9fa;
+}
+</style>
+```
+
+## Examples
+
+### Basic Dropdown
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Dropdown } from "@umbra-ui/core";
+import type { DropdownItem } from "@umbra-ui/core";
+
+const selectedItem = ref<DropdownItem | null>(null);
+
+const items: DropdownItem[] = [
+  { id: "apple", title: "Apple" },
+  { id: "banana", title: "Banana" },
+  { id: "cherry", title: "Cherry" },
+  { id: "date", title: "Date" },
+];
+</script>
+
+<template>
+  <Dropdown
+    :items="items"
+    v-model="selectedItem"
+    placeholder="Select a fruit"
+  />
+</template>
+```
+
+### Dropdown with Subtitles
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Dropdown } from "@umbra-ui/core";
+import type { DropdownItem } from "@umbra-ui/core";
+
+const selectedUser = ref<DropdownItem | null>(null);
+
+const users: DropdownItem[] = [
+  { id: "1", title: "John Doe", subtitle: "Software Engineer" },
+  { id: "2", title: "Jane Smith", subtitle: "Product Manager" },
+  { id: "3", title: "Bob Johnson", subtitle: "Designer" },
+  { id: "4", title: "Alice Brown", subtitle: "Marketing Lead" },
+];
+</script>
+
+<template>
+  <Dropdown
+    :items="users"
+    v-model="selectedUser"
+    placeholder="Select a team member"
+  />
+</template>
+```
+
+### Dropdown with Disabled Items
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Dropdown } from "@umbra-ui/core";
+import type { DropdownItem } from "@umbra-ui/core";
+
+const selectedPlan = ref<DropdownItem | null>(null);
+
+const plans: DropdownItem[] = [
+  { id: "free", title: "Free Plan", subtitle: "Basic features" },
+  { id: "pro", title: "Pro Plan", subtitle: "Advanced features" },
+  {
+    id: "enterprise",
+    title: "Enterprise Plan",
+    subtitle: "All features",
+    disabled: true,
+  },
+];
+</script>
+
+<template>
+  <Dropdown :items="plans" v-model="selectedPlan" placeholder="Choose a plan" />
+</template>
+```
+
+### Form Integration
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { Dropdown } from "@umbra-ui/core";
+import type { DropdownItem } from "@umbra-ui/core";
+
+interface FormData {
+  country: DropdownItem | null;
+  city: DropdownItem | null;
+  language: DropdownItem | null;
+}
+
+const formData = ref<FormData>({
+  country: null,
+  city: null,
+  language: null,
+});
+
+const countries: DropdownItem[] = [
+  { id: "us", title: "United States" },
+  { id: "ca", title: "Canada" },
+  { id: "uk", title: "United Kingdom" },
+  { id: "de", title: "Germany" },
+];
+
+const cities: DropdownItem[] = [
+  { id: "nyc", title: "New York" },
+  { id: "la", title: "Los Angeles" },
+  { id: "chicago", title: "Chicago" },
+];
+
+const languages: DropdownItem[] = [
+  { id: "en", title: "English" },
+  { id: "es", title: "Spanish" },
+  { id: "fr", title: "French" },
+  { id: "de", title: "German" },
+];
+
+const submitForm = () => {
+  if (!formData.value.country || !formData.value.language) {
+    alert("Please fill in all required fields");
+    return;
+  }
+
+  console.log("Form submitted:", formData.value);
+};
+</script>
+
+<template>
+  <form class="form-example" @submit.prevent="submitForm">
+    <div class="form-group">
+      <label>Country *</label>
+      <Dropdown
+        :items="countries"
+        v-model="formData.country"
+        placeholder="Select country"
+      />
+    </div>
+
+    <div class="form-group">
+      <label>City</label>
+      <Dropdown
+        :items="cities"
+        v-model="formData.city"
+        placeholder="Select city"
+      />
+    </div>
+
+    <div class="form-group">
+      <label>Language *</label>
+      <Dropdown
+        :items="languages"
+        v-model="formData.language"
+        placeholder="Select language"
+      />
+    </div>
+
+    <button type="submit">Submit</button>
+  </form>
+</template>
+
+<style module>
+.form-example {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  max-width: 400px;
+}
+
+.form-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+</style>
+```
+
+## Keyboard Navigation
+
+The Dropdown component supports full keyboard navigation:
+
+- **Enter/Space/Arrow Down**: Open dropdown when closed
+- **Arrow Down**: Focus next item
+- **Arrow Up**: Focus previous item
+- **Enter**: Select focused item
+- **Escape**: Close dropdown
+
+## Accessibility Features
+
+- Full ARIA support with proper roles (`combobox`, `listbox`, `option`)
+- Keyboard navigation support
+- Screen reader friendly
+- Focus management
+- Proper labeling and descriptions
+
+## Notes
+
+- The dropdown automatically positions itself above or below the button based on available space
+- Global overlay system prevents multiple dropdowns from interfering with each other
+- Smooth animations for opening/closing with proper transitions
+- Responsive positioning that adjusts to window resize and scroll events
+- Support for both light and dark themes
+- The component uses a shared overlay system across all instances for better performance
+- Items can be disabled by setting the `disabled` property to `true`
+- The dropdown supports both simple titles and titles with subtitles

package/dist/components/controls/Dropdown/theme.css

@@ -0,0 +1,50 @@
+/* Light theme - semantic naming for dropdown properties */
+:root {
+  /* Dropdown popover colors */
+  --dropdown-popover-bg: #ffffff;
+  --dropdown-popover-border: 1px solid rgba(0, 0, 0, 0.1);
+  --dropdown-shadow-dark: transparent;
+  --dropdown-shadow-light: rgba(255, 255, 255, 0.7);
+
+  /* Dropdown item colors */
+  --dropdown-item-border: rgba(0, 0, 0, 0.08);
+  --dropdown-item-hover-bg: #f0f2f4;
+  --dropdown-item-focused-bg: rgba(0, 0, 0, 0.04);
+  --dropdown-item-selected-bg: rgba(0, 144, 255, 0.1);
+  --dropdown-item-selected-hover-bg: rgba(0, 144, 255, 0.15);
+  --dropdown-item-subtitle: #60646c;
+
+  /* Icon colors - default and secondary styles */
+  --dropdown-icon-color: #1a1d23;
+  --dropdown-icon-color-default: #1a1d23;
+  --dropdown-icon-color-secondary: #60646c;
+
+  /* Overlay color */
+  --dropdown-overlay-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* Dark theme */
+.dark,
+.dark-theme {
+  /* Dropdown popover colors */
+  --dropdown-popover-bg: #484848;
+  --dropdown-popover-border: none;
+  --dropdown-shadow-dark: rgba(0, 0, 0, 0.21);
+  --dropdown-shadow-light: rgba(255, 255, 255, 0.1);
+
+  /* Dropdown item colors */
+  --dropdown-item-border: rgba(255, 255, 255, 0.15);
+  --dropdown-item-hover-bg: #222222;
+  --dropdown-item-focused-bg: rgba(255, 255, 255, 0.05);
+  --dropdown-item-selected-bg: rgba(255, 255, 255, 0.15);
+  --dropdown-item-selected-hover-bg: rgba(255, 255, 255, 0.25);
+  --dropdown-item-subtitle: #b4b4b4;
+
+  /* Icon colors - keeping default and secondary styles */
+  --dropdown-icon-color: #eeeeee;
+  --dropdown-icon-color-default: #eeeeee;
+  --dropdown-icon-color-secondary: #60646c;
+
+  /* Overlay color */
+  --dropdown-overlay-bg: rgba(0, 0, 0, 0.5);
+}

package/dist/components/controls/Dropdown/types.ts

@@ -0,0 +1,6 @@
+import { ControlItem } from "../SegmentedControl/types";
+
+// Updated DropdownItem interface with required id
+export interface DropdownItem extends ControlItem {
+  id: string | number;
+}

package/dist/components/controls/IconButton/IconButton.vue

@@ -0,0 +1,267 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { CircleAnimOutlineIcon, icons, type IconKey } from "@umbra.ui/icons";
+import type { TooltipConfig } from "../../indicators/Tooltip/types";
+import "./theme.css";
+
+interface Props {
+  iconName?: IconKey;
+  buttonType?: "round" | "square" | "plain";
+  buttonStyle?: "primary" | "secondary" | "tertiary" | "quaternary";
+  state?: "normal" | "active" | "disabled";
+  buttonSize?: number;
+  tooltip?: string | TooltipConfig;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  iconName: "heart",
+  buttonType: "round",
+  buttonStyle: "primary",
+  state: "normal",
+  buttonSize: 16,
+});
+
+const emit = defineEmits(["update:state", "click"]);
+
+const handleClick = (event: MouseEvent) => {
+  emit("click", event);
+};
+
+const buttonColor = computed(() => {
+  switch (props.buttonStyle) {
+    case "primary":
+      return "var(--iconbutton-primary-bg)";
+    case "secondary":
+      return "var(--iconbutton-secondary-bg)";
+    case "tertiary":
+      return "var(--iconbutton-tertiary-bg)";
+    case "quaternary":
+      return "var(--iconbutton-quaternary-bg)";
+  }
+});
+
+const buttonHoverColor = computed(() => {
+  switch (props.buttonStyle) {
+    case "primary":
+      return "var(--iconbutton-primary-hover-bg)";
+    case "secondary":
+      return "var(--iconbutton-secondary-hover-bg)";
+    case "tertiary":
+      return "var(--iconbutton-tertiary-hover-bg)";
+    case "quaternary":
+      return "var(--iconbutton-quaternary-hover-bg)";
+  }
+});
+
+const buttonColorWithOpacity = computed(() => {
+  return `color-mix(in srgb, var(--button-color) 20%, transparent)`;
+});
+
+const iconColor = computed(() => {
+  // All predefined styles use white
+  return "var(--iconbutton-icon-color)";
+});
+
+const IconComponent = computed(() => {
+  if (!props.iconName) return null;
+  return icons[props.iconName as keyof typeof icons] || null;
+});
+</script>
+
+<template>
+  <div
+    v-tooltip="tooltip"
+    @click="handleClick"
+    :class="[
+      $style.container,
+      $style[buttonType!],
+      $style[buttonStyle!],
+      $style[state!],
+    ]"
+    :style="{
+      '--button-color': buttonColor,
+      '--button-hover-color': buttonHoverColor,
+      '--button-color-opacity': buttonColorWithOpacity,
+      '--button-size': `${buttonSize}px`,
+      '--icon-color': iconColor,
+    }"
+  >
+    <component v-if="IconComponent" :is="IconComponent" :class="$style.icon" />
+    <div :class="$style.animated" v-if="state === 'active'">
+      <CircleAnimOutlineIcon />
+    </div>
+  </div>
+</template>
+
+<style module>
+.container {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--button-color);
+  padding: 0.5rem;
+  transition: 0.3s ease-in-out transform, 0.3s ease-in-out background-color,
+    0.3s ease-in-out box-shadow, 0.3s ease-in-out border, 0.3s ease-in-out color,
+    0.3s ease-in-out opacity;
+  will-change: transform;
+  width: fit-content;
+  height: fit-content;
+  cursor: pointer;
+}
+
+.container:hover {
+  transform: scale(1.05);
+}
+.container:active {
+  transform: scale(1);
+}
+
+.icon {
+  width: var(--button-size);
+  height: var(--button-size);
+  color: var(--icon-color);
+}
+.round {
+  border-radius: 50%;
+}
+.square {
+  border-radius: 0.353rem;
+  padding: 0.5rem;
+}
+.plain {
+  border-radius: 0;
+  padding: 0;
+  color: var(--button-color);
+  background-color: transparent;
+}
+.plain .icon {
+  color: var(--button-color);
+}
+.plain:hover {
+  transform: scale(1.15);
+}
+.plain:active {
+  transform: scale(1);
+}
+.plain.primary {
+  background-color: transparent;
+  color: var(--iconbutton-plain-primary);
+  box-shadow: none;
+}
+.plain.primary:hover {
+  background-color: transparent;
+  box-shadow: none;
+}
+.plain.secondary {
+  background-color: transparent;
+  color: var(--iconbutton-plain-secondary);
+  border: none;
+}
+.plain.secondary:hover {
+  background-color: transparent;
+  box-shadow: none;
+  border: none;
+}
+.plain.secondary .icon {
+  color: var(--iconbutton-plain-secondary);
+}
+.plain.tertiary .icon {
+  color: var(--iconbutton-plain-tertiary);
+}
+.plain.quaternary .icon {
+  color: var(--iconbutton-plain-quaternary);
+}
+.plain.tertiary {
+  background-color: transparent;
+  color: var(--iconbutton-plain-tertiary);
+  border: none;
+  box-shadow: none;
+}
+.plain.tertiary:hover {
+  background-color: transparent;
+  box-shadow: none;
+  border: none;
+}
+.plain.quaternary {
+  background-color: transparent;
+  color: var(--iconbutton-plain-quaternary);
+  border: none;
+}
+.plain.quaternary:hover {
+  background-color: transparent;
+  box-shadow: none;
+  border: none;
+}
+.primary {
+  background-color: var(--iconbutton-primary-bg);
+  box-shadow: inset 0 0 0 1px var(--iconbutton-primary-border);
+  color: var(--iconbutton-icon-primary-color);
+}
+.primary.round .icon {
+  color: var(--iconbutton-icon-primary-color);
+}
+.primary.square .icon {
+  color: var(--iconbutton-icon-primary-color);
+}
+.primary:hover {
+  background-color: var(--button-hover-color);
+  box-shadow: inset 0 0 0 1px var(--iconbutton-primary-hover-border);
+}
+.secondary {
+  background-color: var(--iconbutton-secondary-bg);
+  border: 1px solid var(--iconbutton-secondary-border);
+}
+.secondary:hover {
+  background-color: var(--button-hover-color);
+  border: 1px solid var(--iconbutton-secondary-hover-border);
+}
+.tertiary {
+  background-color: var(--iconbutton-tertiary-bg);
+  border: 1px solid var(--iconbutton-tertiary-border);
+}
+.tertiary:hover {
+  background-color: var(--iconbutton-tertiary-hover-bg);
+  border: 1px solid var(--iconbutton-tertiary-hover-border);
+}
+.quaternary {
+  background-color: var(--iconbutton-quaternary-bg);
+  border: 1px solid var(--iconbutton-quaternary-border);
+}
+.quaternary:hover {
+  background-color: var(--iconbutton-quaternary-hover-bg);
+  border: 1px solid var(--iconbutton-quaternary-hover-border);
+}
+
+.active {
+  opacity: var(--iconbutton-active-opacity);
+  cursor: pointer;
+  pointer-events: none;
+}
+.plain.active {
+  padding: 0.5rem;
+}
+
+.disabled {
+  opacity: var(--iconbutton-disabled-opacity);
+  cursor: not-allowed;
+  pointer-events: none;
+  filter: grayscale(100%);
+}
+
+.animated {
+  position: absolute;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  right: 0;
+  border-radius: inherit;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: visible;
+}
+.animated svg {
+  width: 90%;
+  height: 90%;
+}
+</style>