8 initial readme file (#19)

- added top-level readme
- inner readme for storybook
- updated stories for all existing implementations

Author: bubulux

.devcontainer/devcontainer.json

@@ -22,7 +22,8 @@
                 "eamodio.gitlens",
                 "wayou.vscode-todo-highlight",
                 "PKief.material-icon-theme",
-                "yoavbls.pretty-ts-errors"
+                "yoavbls.pretty-ts-errors",
+                "unifiedjs.vscode-mdx"
             ]
         }
     },

.eslintrc.yml

@@ -50,8 +50,6 @@ extends:
   - "plugin:jest/style"
   # -- STORYBOOK --
   # NOTE: Quote from docs: "This plugin will only be applied to files following the *.stories.* (we recommend this) or *.story.* pattern."
-  # Its recommended to lint also the config files in .storybook, which in our current file context, is painfull to achieve, so this is emmited.
-  # It would not have made any major difference anyhow, can only help with mistyped addon names, we will survive without it...
   - "plugin:storybook/recommended"
 
   # --------------------------- Formatting -------------------------

.storybook/main.ts

@@ -1,7 +1,7 @@
 import { StorybookConfig } from "@storybook/react-vite";
 
 const config: StorybookConfig = {
-  stories: ["../**/stories.@(ts|tsx)"],
+  stories: ["../**/stories.@(ts|tsx)", "../**/readme.mdx"],
   addons: ["@storybook/addon-essentials"],
   framework: "@storybook/react-vite",
 };

readme.md

@@ -1,3 +1,29 @@
-TEST FOR PUBLISHING; UNSTABLE DO NOT USE
+**Disclaimer:** _I am not affiliated in any way with Microsoft or Fluent UI. This is **NOT** an official repository from the Fluent UI ecosystem_.
 
-FURTHER REL FOR PIPELINE TEST 0.0.2
+### Who is this for?
+
+This library is aimed at folks who work with Microsoft's Fluent UI library but think it lacks some features here and there.
+
+### Is this stable?
+
+Not quite yet, from `1.*` onward it will be, as long as its in `0.*` consider it unstable.
+
+### What does it contain?
+
+It contains helpful hooks, components, and theme utilities that I was maintaining across different projects. I decided to create this central repository to share these utilities.
+
+These utilities can be common layout utilities (like `Flex`, `Grid`, etc.), generic and library-specific hooks, extended theme tokens, common animations, and also full-fledged components that are not yet available in Fluent UI itself (like `Pagination`, for instance).
+
+### Where can I find the docs?
+
+The library documentation resides at a dedicated [Storybook](https://bubulux.github.io/fluentui-helpers). You will also find planned updates and preview components there.
+
+### How long will I be committed to this?
+
+I am maintaining two larger projects with Fluent UI, one private and one for my company, so there are long-lasting factors that will bind me to this for a while.
+
+### How to contribute or report bugs?
+
+If there are any bugs, please open an issue on GitHub.
+
+If you want to contribute (other than a bug fix) or suggest a change, open a discussion thread :)

src/hooks/useFuiProviderNode.ts src/hooks/useFuiProviderNode/hook.ts

@@ -0,0 +1,3 @@
+import useFuiProviderNode from "@hooks/useFuiProviderNode/hook";
+
+export default useFuiProviderNode;

src/hooks/useFuiProviderNode/index.ts

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { Tooltip, Button } from "@fluentui/react-components";
+import useFuiProviderNode from "@hooks/useFuiProviderNode";
+
+/**
+ * @description
+ * - when you use a component in fluent that requires the parent provider node, for example for relative positioning, you can use this hook to get the parent provider node
+ * - some components like Tooltip for example allow to set a mountNode prop, which is the parent provider node
+ * - this will only work if you have exactly one provider node in your app
+ *
+ * @example
+ *
+ * ```tsx
+ * import { Tooltip, Button } from "@fluentui/react-components";
+ * import useFuiProviderNode from "@hooks/useFuiProviderNode";
+ *
+ * export default function SomeHigherComponent() {
+ *  const { fuiProviderNode } = useFuiProviderNode();
+ *  return (
+ *    <Tooltip
+ *     content="This is a tooltip that uses the provider node"
+ *     mountNode={fuiProviderNode}
+ *     relationship="label"
+ *    >
+ *     <Button>Hover me</Button>
+ *    </Tooltip>
+ *  );
+ * }
+ * ```
+ */
+export function Wrapper({ hasProviderNode }: { hasProviderNode: boolean }) {
+  const { fuiProviderNode } = useFuiProviderNode();
+  return hasProviderNode ? (
+    <Tooltip
+      content="This is a tooltip that uses the provider node"
+      mountNode={fuiProviderNode}
+      relationship="label"
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+  ) : (
+    <Tooltip
+      content="This is a tooltip that relies on a unspecified provider node"
+      relationship="label"
+    >
+      <Button>Hover me</Button>
+    </Tooltip>
+  );
+}
+
+const meta: Meta = {
+  title: "Hooks/Specific/useFuiProviderNode",
+  component: Wrapper,
+  args: {
+    hasProviderNode: true,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Wrapper>;
+
+export const WithNodeFromHook: Story = {};
+
+export const DefaultProviderNode: Story = {
+  args: { hasProviderNode: false },
+};

src/hooks/useFuiProviderNode/stories.tsx

@@ -0,0 +1,24 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Introduction" />
+
+### Implemented
+
+For the implemented features just browse the Storybook.
+Not only visual components are there, but also hooks and other utilities showcase through wrappers.
+
+### Planned
+
+#### Components
+
+- Atoms: Pagination
+- Layout: Grid (not sure, might cause more problems than it solves)
+- Animations: FadeIn, FadeOut
+
+#### Hooks
+
+_nothing planned_
+
+#### Theme
+
+- More materials / Morphism for web: Window 11 brings lots of glass / acrylic effects from the [fluent UI language](https://fluent2.microsoft.design/material), there should also be a way to access these in web apps.