@umbra.ui/core 0.1.0

package/src/components/controls/IconButton/README.md

@@ -0,0 +1,502 @@
+# IconButton
+
+A versatile icon button component built with Vue 3 Composition API and TypeScript. The IconButton component provides multiple visual styles, sizes, and states with built-in animations and accessibility features.
+
+## Installation/Import
+
+```typescript
+import { IconButton } from "@umbra-ui/core";
+import type { IconKey } from "@umbra-ui/icons";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for icon components and types)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { IconButton } from "@umbra-ui/core";
+
+const handleClick = (event: MouseEvent) => {
+  console.log("Icon button clicked!", event);
+};
+</script>
+
+<template>
+  <IconButton
+    icon-name="heart"
+    button-style="primary"
+    button-type="round"
+    @click="handleClick"
+  />
+</template>
+```
+
+## Props
+
+| Prop Name     | Type                                                     | Required | Default     | Description                          |
+| ------------- | -------------------------------------------------------- | -------- | ----------- | ------------------------------------ |
+| `iconName`    | `IconKey`                                                | No       | `"heart"`   | Name of the icon to display          |
+| `buttonType`  | `"round" \| "square" \| "plain"`                         | No       | `"round"`   | Visual style variant of the button   |
+| `buttonStyle` | `"primary" \| "secondary" \| "tertiary" \| "quaternary"` | No       | `"primary"` | Color scheme for the button          |
+| `state`       | `"normal" \| "active" \| "disabled"`                     | No       | `"normal"`  | Current state of the button          |
+| `buttonSize`  | `number`                                                 | No       | `16`        | Size of the icon in pixels           |
+| `tooltip`     | `string \| TooltipConfig`                                | No       | -           | Tooltip text or configuration object |
+
+### Button Types
+
+- **`round`**: Circular button with rounded background
+- **`square`**: Square button with rounded corners
+- **`plain`**: Minimal button with no background, just the icon
+
+### Button Styles
+
+- **`primary`**: Blue color scheme (default)
+- **`secondary`**: Light gray color scheme
+- **`tertiary`**: Very light gray color scheme
+- **`quaternary`**: Lightest gray color scheme
+
+### Available Icons
+
+The component supports all icons from the `@umbra-ui/icons` package. Common icons include:
+
+- `heart`, `star`, `bookmark`, `share`, `download`, `upload`
+- `edit`, `delete`, `add`, `remove`, `close`, `check`
+- `arrow-left`, `arrow-right`, `arrow-up`, `arrow-down`
+- `search`, `filter`, `settings`, `menu`, `user`
+- And many more...
+
+## Events
+
+| Event Name     | Payload Type                         | Description                           |
+| -------------- | ------------------------------------ | ------------------------------------- |
+| `update:state` | `"normal" \| "active" \| "disabled"` | Emitted when the button state changes |
+| `click`        | `MouseEvent`                         | Emitted when the button is clicked    |
+
+### Event Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconButton } from "@umbra-ui/core";
+
+const buttonState = ref<"normal" | "active" | "disabled">("normal");
+
+const handleClick = (event: MouseEvent) => {
+  console.log("Button clicked at:", event.clientX, event.clientY);
+};
+
+const handleStateChange = (newState: "normal" | "active" | "disabled") => {
+  console.log("Button state changed to:", newState);
+  buttonState.value = newState;
+};
+</script>
+
+<template>
+  <IconButton
+    icon-name="heart"
+    :state="buttonState"
+    @click="handleClick"
+    @update:state="handleStateChange"
+  />
+</template>
+```
+
+## Slots
+
+This component does not use slots. The icon content is controlled via the `iconName` prop.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs via `defineExpose`.
+
+## CSS Customization
+
+The IconButton component uses CSS custom properties that can be overridden to customize the appearance:
+
+### Color Variables
+
+```css
+/* IconButton background colors */
+--iconbutton-primary-bg: #0090ff;
+--iconbutton-primary-hover-bg: #0588f0;
+--iconbutton-secondary-bg: #ffffff;
+--iconbutton-secondary-hover-bg: #fcfcfc;
+--iconbutton-tertiary-bg: #f9f9f9;
+--iconbutton-tertiary-hover-bg: #f0f0f0;
+--iconbutton-quaternary-bg: #f0f0f0;
+--iconbutton-quaternary-hover-bg: #e8e8e8;
+
+/* IconButton border colors */
+--iconbutton-primary-border: rgba(0, 0, 0, 0.25);
+--iconbutton-primary-hover-border: rgba(0, 0, 0, 0.5);
+--iconbutton-secondary-border: #d9d9d9;
+--iconbutton-secondary-hover-border: #8b8d98;
+--iconbutton-tertiary-border: #d9d9d9;
+--iconbutton-tertiary-hover-border: #9b9ea6;
+--iconbutton-quaternary-border: #d9d9d9;
+--iconbutton-quaternary-hover-border: #b2b5bd;
+
+/* IconButton plain colors */
+--iconbutton-plain-primary: #0090ff;
+--iconbutton-plain-secondary: #374151;
+--iconbutton-plain-tertiary: #8d8d8d;
+--iconbutton-plain-quaternary: #cecece;
+
+/* Icon colors */
+--iconbutton-icon-color: #8d8d8d;
+--iconbutton-icon-primary-color: #ffffff;
+
+/* State variables */
+--iconbutton-active-opacity: 0.8;
+--iconbutton-disabled-opacity: 0.5;
+```
+
+### Custom Styling Example
+
+```vue
+<template>
+  <IconButton
+    icon-name="heart"
+    button-style="primary"
+    class="custom-icon-button"
+  />
+</template>
+
+<style>
+.custom-icon-button {
+  --iconbutton-primary-bg: #ff6b6b;
+  --iconbutton-primary-hover-bg: #ff5252;
+  --iconbutton-icon-primary-color: #ffffff;
+}
+</style>
+```
+
+## Examples
+
+### Different Button Types
+
+```vue
+<script setup lang="ts">
+import { IconButton } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div class="button-examples">
+    <IconButton icon-name="heart" button-type="round" />
+    <IconButton icon-name="star" button-type="square" />
+    <IconButton icon-name="bookmark" button-type="plain" />
+  </div>
+</template>
+
+<style module>
+.button-examples {
+  display: flex;
+  gap: 1rem;
+  align-items: center;
+}
+</style>
+```
+
+### Different Button Styles
+
+```vue
+<script setup lang="ts">
+import { IconButton } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div class="style-examples">
+    <IconButton icon-name="heart" button-style="primary" />
+    <IconButton icon-name="star" button-style="secondary" />
+    <IconButton icon-name="bookmark" button-style="tertiary" />
+    <IconButton icon-name="share" button-style="quaternary" />
+  </div>
+</template>
+
+<style module>
+.style-examples {
+  display: flex;
+  gap: 1rem;
+  align-items: center;
+}
+</style>
+```
+
+### Different Sizes
+
+```vue
+<script setup lang="ts">
+import { IconButton } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div class="size-examples">
+    <IconButton icon-name="heart" :button-size="12" />
+    <IconButton icon-name="star" :button-size="16" />
+    <IconButton icon-name="bookmark" :button-size="20" />
+    <IconButton icon-name="share" :button-size="24" />
+  </div>
+</template>
+
+<style module>
+.size-examples {
+  display: flex;
+  gap: 1rem;
+  align-items: center;
+}
+</style>
+```
+
+### Button States and Event Handling
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconButton } from "@umbra-ui/core";
+
+const likeState = ref<"normal" | "active" | "disabled">("normal");
+const likeCount = ref(0);
+
+const handleLike = (event: MouseEvent) => {
+  likeCount.value++;
+  console.log(`Liked ${likeCount.value} times`);
+
+  // Simulate loading state
+  likeState.value = "active";
+  setTimeout(() => {
+    likeState.value = "normal";
+  }, 1000);
+};
+
+const toggleDisabled = () => {
+  likeState.value = likeState.value === "disabled" ? "normal" : "disabled";
+};
+</script>
+
+<template>
+  <div class="state-examples">
+    <div class="like-section">
+      <IconButton
+        icon-name="heart"
+        :state="likeState"
+        button-style="primary"
+        @click="handleLike"
+      />
+      <span>{{ likeCount }} likes</span>
+    </div>
+
+    <IconButton
+      icon-name="settings"
+      button-style="secondary"
+      @click="toggleDisabled"
+    />
+  </div>
+</template>
+
+<style module>
+.state-examples {
+  display: flex;
+  gap: 2rem;
+  align-items: center;
+}
+
+.like-section {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+</style>
+```
+
+### Action Bar
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconButton } from "@umbra-ui/core";
+
+const isBookmarked = ref(false);
+const isLiked = ref(false);
+const isShared = ref(false);
+
+const toggleBookmark = () => {
+  isBookmarked.value = !isBookmarked.value;
+};
+
+const toggleLike = () => {
+  isLiked.value = !isLiked.value;
+};
+
+const handleShare = () => {
+  isShared.value = true;
+  setTimeout(() => {
+    isShared.value = false;
+  }, 1000);
+};
+</script>
+
+<template>
+  <div class="action-bar">
+    <IconButton
+      :icon-name="isBookmarked ? 'bookmark-filled' : 'bookmark'"
+      :button-style="isBookmarked ? 'primary' : 'secondary'"
+      @click="toggleBookmark"
+    />
+
+    <IconButton
+      :icon-name="isLiked ? 'heart-filled' : 'heart'"
+      :button-style="isLiked ? 'primary' : 'secondary'"
+      @click="toggleLike"
+    />
+
+    <IconButton
+      icon-name="share"
+      :state="isShared ? 'active' : 'normal'"
+      button-style="secondary"
+      @click="handleShare"
+    />
+
+    <IconButton icon-name="download" button-style="tertiary" />
+  </div>
+</template>
+
+<style module>
+.action-bar {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+  padding: 1rem;
+  background-color: #f5f5f5;
+  border-radius: 0.5rem;
+}
+</style>
+```
+
+### With Tooltips
+
+```vue
+<script setup lang="ts">
+import { IconButton } from "@umbra-ui/core";
+</script>
+
+<template>
+  <div class="tooltip-examples">
+    <IconButton icon-name="heart" tooltip="Add to favorites" />
+
+    <IconButton
+      icon-name="share"
+      :tooltip="{
+        content: 'Share this item',
+        placement: 'top',
+        delay: 500,
+      }"
+    />
+
+    <IconButton icon-name="settings" tooltip="Open settings" />
+  </div>
+</template>
+
+<style module>
+.tooltip-examples {
+  display: flex;
+  gap: 1rem;
+  align-items: center;
+}
+</style>
+```
+
+### Navigation Icons
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { IconButton } from "@umbra-ui/core";
+
+const currentPage = ref(1);
+const totalPages = ref(10);
+
+const goToPrevious = () => {
+  if (currentPage.value > 1) {
+    currentPage.value--;
+  }
+};
+
+const goToNext = () => {
+  if (currentPage.value < totalPages.value) {
+    currentPage.value++;
+  }
+};
+
+const goToFirst = () => {
+  currentPage.value = 1;
+};
+
+const goToLast = () => {
+  currentPage.value = totalPages.value;
+};
+</script>
+
+<template>
+  <div class="navigation">
+    <IconButton
+      icon-name="chevron-double-left"
+      button-style="secondary"
+      :state="currentPage === 1 ? 'disabled' : 'normal'"
+      @click="goToFirst"
+    />
+
+    <IconButton
+      icon-name="chevron-left"
+      button-style="secondary"
+      :state="currentPage === 1 ? 'disabled' : 'normal'"
+      @click="goToPrevious"
+    />
+
+    <span class="page-info"> {{ currentPage }} of {{ totalPages }} </span>
+
+    <IconButton
+      icon-name="chevron-right"
+      button-style="secondary"
+      :state="currentPage === totalPages ? 'disabled' : 'normal'"
+      @click="goToNext"
+    />
+
+    <IconButton
+      icon-name="chevron-double-right"
+      button-style="secondary"
+      :state="currentPage === totalPages ? 'disabled' : 'normal'"
+      @click="goToLast"
+    />
+  </div>
+</template>
+
+<style module>
+.navigation {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.page-info {
+  margin: 0 1rem;
+  font-weight: 500;
+}
+</style>
+```
+
+## Notes
+
+- The button includes smooth hover animations with scale transforms
+- Active state shows a circular animation using the `CircleAnimOutlineIcon`
+- Disabled state applies grayscale filter and prevents pointer events
+- All color schemes support both light and dark themes
+- The component is fully accessible with proper ARIA attributes
+- Plain buttons have different hover behavior (scale 1.15 instead of 1.05)
+- Icon size is controlled via the `buttonSize` prop in pixels
+- The component automatically handles icon loading from the icons package
+- Tooltips are supported for better user experience
+- The component supports all icons available in the `@umbra-ui/icons` package

package/src/components/controls/IconButton/theme.css

@@ -0,0 +1,89 @@
+/* Light theme using Colors */
+:root {
+  /* IconButton background colors */
+  --iconbutton-primary-bg: #0090ff; /* blue9 - same as button primary */
+  --iconbutton-primary-hover-bg: #0588f0; /* blue10 - same as button primary hover */
+  --iconbutton-secondary-bg: #ffffff; /* gray5 - light background for light mode */
+  --iconbutton-secondary-hover-bg: #fcfcfc; /* gray6 - light hover for light mode */
+  --iconbutton-tertiary-bg: #f9f9f9; /* gray3 - lighter background for light mode */
+  --iconbutton-tertiary-hover-bg: #f0f0f0; /* gray4 - lighter hover for light mode */
+  --iconbutton-quaternary-bg: #f0f0f0; /* gray2 - lightest background for light mode */
+  --iconbutton-quaternary-hover-bg: #e8e8e8; /* gray3 - lightest hover for light mode */
+
+  /* IconButton border colors */
+  --iconbutton-primary-border: rgba(0, 0, 0, 0.25);
+  --iconbutton-primary-hover-border: rgba(
+    0,
+    0,
+    0,
+    0.5
+  ); /* Original dark mode value */
+  --iconbutton-secondary-border: #d9d9d9; /* gray8 - light border for light mode */
+  --iconbutton-secondary-hover-border: #8b8d98; /* gray9 - light hover border */
+  --iconbutton-tertiary-border: #d9d9d9; /* gray7 - lighter border for light mode */
+  --iconbutton-tertiary-hover-border: #9b9ea6; /* gray8 - lighter hover border */
+  --iconbutton-quaternary-border: #d9d9d9; /* gray6 - lightest border for light mode */
+  --iconbutton-quaternary-hover-border: #b2b5bd; /* gray7 - lightest hover border */
+
+  /* IconButton plain colors */
+  --iconbutton-plain-primary: #0090ff; /* blue9 - same as button primary */
+  --iconbutton-plain-secondary: #374151;
+  --iconbutton-plain-tertiary: #8d8d8d;
+  --iconbutton-plain-quaternary: #cecece;
+
+  /* Icon colors */
+  --iconbutton-icon-color: #8d8d8d;
+  --iconbutton-icon-primary-color: #ffffff; /* white - for primary buttons */
+
+  /* State colors */
+  --iconbutton-active-opacity: 0.8;
+  --iconbutton-disabled-opacity: 0.5;
+}
+
+/* Dark theme */
+.dark,
+.dark-theme {
+  /* IconButton background colors */
+  --iconbutton-primary-bg: #0090ff; /* blue9 - same as button primary */
+  --iconbutton-primary-hover-bg: #1a9eff; /* Original dark mode value */
+  --iconbutton-secondary-bg: #484848; /* Original dark mode value */
+  --iconbutton-secondary-hover-bg: #5a5a5a; /* Original dark mode value */
+  --iconbutton-tertiary-bg: #313131; /* Original dark mode value */
+  --iconbutton-tertiary-hover-bg: #484848; /* Original dark mode value */
+  --iconbutton-quaternary-bg: #222222; /* Original dark mode value */
+  --iconbutton-quaternary-hover-bg: #313131; /* Original dark mode value */
+
+  /* IconButton border colors */
+  --iconbutton-primary-border: rgba(
+    255,
+    255,
+    255,
+    0.25
+  ); /* Original dark mode value */
+  --iconbutton-primary-hover-border: rgba(
+    255,
+    255,
+    255,
+    0.5
+  ); /* Original dark mode value */
+  --iconbutton-secondary-border: #606060; /* Original dark mode value */
+  --iconbutton-secondary-hover-border: #606060; /* Original dark mode value */
+  --iconbutton-tertiary-border: #3a3a3a; /* Original dark mode value */
+  --iconbutton-tertiary-hover-border: #606060; /* Original dark mode value */
+  --iconbutton-quaternary-border: #2a2a2a; /* Original dark mode value */
+  --iconbutton-quaternary-hover-border: #3a3a3a; /* Original dark mode value */
+
+  /* IconButton plain colors */
+  --iconbutton-plain-primary: #0090ff; /* blue9 - same as button primary */
+  --iconbutton-plain-secondary: #eeeeee; /* Original dark mode value */
+  --iconbutton-plain-tertiary: #b4b4b4; /* Original dark mode value */
+  --iconbutton-plain-quaternary: #7b7b7b; /* Original dark mode value */
+
+  /* Icon colors */
+  --iconbutton-icon-color: #ffffff; /* white - for filled buttons */
+  --iconbutton-icon-primary-color: #ffffff; /* white - for primary buttons */
+
+  /* State colors */
+  --iconbutton-active-opacity: 0.8;
+  --iconbutton-disabled-opacity: 0.5;
+}