Add search spotlight with registration hook (#82)

* wip: add spotlight * feat: add spotlight with registration hook and group chips * chore: address pull request feedback * docs: add documentation for usage of spotlight actions * fix: deepsource issue JS-0415 * feat: add support for dependencies of spotlight actions * fix: lockfile broken * feat: add hover effect for spotlight action * docs: Add documentation about dependency array * refactor: remove test spotlight actions, disallow all as group for actions * fix: type issues * chore: address pull request feedback
2024-02-17 14:11:23 +01:00
parent 3577bd6ac3
commit d5025da789
25 changed files with 2833 additions and 5243 deletions
--- a/packages/spotlight/ReadMe.md
+++ b/packages/spotlight/ReadMe.md
@@ -0,0 +1,146 @@
+# Spotlight
+
+Spotlight is the search functionality of Homarr. It can be opened by pressing `Ctrl + K` or `Cmd + K` on Mac. It is a quick way to search for anything in Homarr.
+
+## API
+
+### SpotlightActionData
+
+The [SpotlightActionData](./src/type.ts) is the data structure that is used to define the actions that are shown in the spotlight.
+
+#### Common properties
+
+| Name                           | Type                                                                                       | Description                                                                         |
+| ------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| id                             | `string`                                                                                   | The id of the action.                                                               |
+| title                          | `string \| (t: TranslationFunction) => string`                                             | The title of the action. Either static or generated with translation function       |
+| description                    | `string \| (t: TranslationFunction) => string`                                             | The description of the action. Either static or generated with translation function |
+| icon                           | `string                                        \| (props: TablerIconProps) => JSX.Element` | The icon of the action. Either a url to an image or a TablerIcon                    |
+| group                          | `string`                                                                                   | The group of the action. By default the groups all, web and action exist.           |
+| ignoreSearchAndOnlyShowInGroup | `boolean`                                                                                  | If true, the action will only be shown in the group and not in the search results.  |
+| type                           | `'link' \| 'button'`                                                                       | The type of the action. Either link or button                                       |
+
+#### Properties for links
+
+| Name | Type     | Description                                                                                                |
+| ---- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| href | `string` | The url the link should navigate to. If %s is contained it will be replaced with the current search query. |
+
+#### Properties for buttons
+
+| Name    | Type                       | Description                                                                               |
+| ------- | -------------------------- | ----------------------------------------------------------------------------------------- |
+| onClick | `() => MaybePromise<void>` | The function that should be called when the button is clicked. It can be async if needed. |
+
+### useRegisterSpotlightActions
+
+The [useRegisterSpotlightActions](./src/data-store.ts) hook is used to register actions to the spotlight. It takes an unique key and the array of [SpotlightActionData](#SpotlightActionData).
+
+#### Usage
+
+The following example shows how to use the `useRegisterSpotlightActions` hook to register an action to the spotlight.
+
+```tsx
+"use client";
+
+import { useRegisterSpotlightActions } from "@homarr/spotlight";
+
+const MyComponent = () => {
+  useRegisterSpotlightActions("my-component", [
+    {
+      id: "my-action",
+      title: "My Action",
+      description: "This is my action",
+      icon: "https://example.com/icon.png",
+      group: "web",
+      type: "link",
+      href: "https://example.com",
+    },
+  ]);
+
+  return <div>My Component</div>;
+};
+```
+
+##### Using translation function
+
+```tsx
+"use client";
+
+import { useRegisterSpotlightActions } from "@homarr/spotlight";
+
+const MyComponent = () => {
+  useRegisterSpotlightActions("my-component", [
+    {
+      id: "my-action",
+      title: (t) => t("some.path.to.translation.key"),
+      description: (t) => t("some.other.path.to.translation.key"),
+      icon: "https://example.com/icon.png",
+      group: "web",
+      type: "link",
+      href: "https://example.com",
+    },
+  ]);
+
+  return <div>Component implementation</div>;
+};
+```
+
+##### Using TablerIcon
+
+```tsx
+"use client";
+
+import { IconUserCog } from "tabler-react";
+
+import { useRegisterSpotlightActions } from "@homarr/spotlight";
+
+const UserMenu = () => {
+  useRegisterSpotlightActions("header-user-menu", [
+    {
+      id: "user-preferences",
+      title: (t) => t("user.preferences.title"),
+      description: (t) => t("user.preferences.description"),
+      icon: IconUserCog,
+      group: "action",
+      type: "link",
+      href: "/user/preferences",
+    },
+  ]);
+
+  return <div>Component implementation</div>;
+};
+```
+
+##### Using dependency array
+
+```tsx
+"use client";
+
+import { IconUserCog } from "tabler-react";
+
+import { useRegisterSpotlightActions } from "@homarr/spotlight";
+
+const ColorSchemeButton = () => {
+  const { colorScheme, toggleColorScheme } = useColorScheme();
+
+  useRegisterSpotlightActions(
+    "toggle-color-scheme",
+    [
+      {
+        id: "toggle-color-scheme",
+        title: (t) => t("common.colorScheme.toggle.title"),
+        description: (t) =>
+          t(`common.colorScheme.toggle.${colorScheme}.description`),
+        icon: colorScheme === "light" ? IconSun : IconMoon,
+        group: "action",
+        type: "button",
+        onClick: toggleColorScheme,
+      },
+    ],
+    [colorScheme],
+  );
+
+  return <div>Component implementation</div>;
+};
+```