feat: update document

packages/docs/src/content/docs/customization/filter.mdx

@@ -0,0 +1,104 @@
+---
+title: Customizing filters
+description: Customizing the available filters in Filter Sphere
+---
+
+Filter Sphere allow you to extend the default filtering capabilities with your own specific logic. This feature is particularly useful when you need to implement complex or domain-specific filtering that isn't covered by the built-in filters.
+
+## Defining a Custom Filter
+
+To add custom filters to Filter Sphere, you can use the `defineTypedFn` function. This allows you to create type-safe, custom filter functions.
+
+Use `defineTypedFn` to create a custom filter:
+
+```ts
+const customFilter = defineTypedFn({
+  name: "your filter name",
+  define: z
+    .function()
+    .args(schemaToFilter, optionalUserInputSchema)
+    .returns(z.boolean()),
+  implement: (value, userInput?) => {
+    // Your filter logic here
+    return boolean;
+  },
+});
+```
+
+- name: A string describing your filter.
+  - By default, the name will be used as the filter label in the UI. You can override this by overriding the `mapFilterName` property in the `useFilterSphere` hook.
+- define: A Zod schema defining the function signature.
+  - First argument: The schema of the data being filtered.
+  - Second argument (optional): The schema for user input, if required.
+- implement: The actual filter logic.
+
+## Using Custom Filters
+
+Add your custom filters to the filterFnList when using the useFilterSphere hook:
+
+```ts
+const { predicate, context } = useFilterSphere({
+  schema: yourSchema,
+  filterFnList: [
+    customFilter,
+    // Other custom filters...
+    ...presetFilter, // Include preset filters if needed
+  ],
+});
+```
+
+This approach allows you to extend Filter Sphere's functionality with your own custom filtering logic while maintaining type safety and integration with the existing system.
+
+Here is an example of using a custom filter function to calculate the average of an array of numbers:
+
+```tsx live {17-29} {38}
+import { z } from "zod";
+import {
+  FilterSphereProvider,
+  FilterBuilder,
+  useFilterSphere,
+  presetFilter,
+  defineTypedFn,
+  type FnSchema,
+} from "@fn-sphere/filter";
+
+const schema = z.object({
+  scores: z.array(z.number()),
+});
+
+const dataFilters: FnSchema[] = [
+  // Define a custom filter function
+  defineTypedFn({
+    name: "Average score is greater than",
+    define: z
+      .function()
+      // The first argument is the schema that needs filtering
+      // and the second argument is the user input
+      .args(z.array(z.number()), z.number())
+      .returns(z.boolean()),
+    implement: (value, input) => {
+      // Implement the filter logic
+      return value.reduce((acc, curr) => acc + curr, 0) / value.length > input;
+    },
+  }),
+  // Preset filters contains all the built-in filters
+  ...presetFilter,
+];
+
+export default function AdvancedFilter() {
+  const { predicate, context } = useFilterSphere({
+    schema,
+    // Pass the custom filters to the filterFnList
+    filterFnList: dataFilters,
+  });
+  return (
+    <FilterSphereProvider context={context}>
+      <FilterBuilder />
+    </FilterSphereProvider>
+  );
+}
+```
+
+## 🚧 Define a generic filter
+
+WIP

packages/docs/src/content/docs/customization/localization.mdx

@@ -0,0 +1,102 @@
+---
+title: Localization
+description: Localize the UI
+---
+
+Filter Sphere provides a variety of ways to localize the UI. This is useful when you want to display the UI in a different language.
+
+## getLocaleText
+
+You can use the `getLocaleText` function to translate the filter UI.
+
+```tsx live {8-10} {20}
+import {
+  FilterSphereProvider,
+  FilterBuilder,
+  useFilterSphere,
+} from "@fn-sphere/filter";
+import { z } from "zod";
+
+const customGetLocaleText = (key: string) => {
+  return `key-${key}`;
+};
+
+const schema = z.object({
+  id: z.number(),
+  name: z.string(),
+});
+
+export default function AdvancedFilter() {
+  const { filterRule, predicate, context } = useFilterSphere({
+    schema,
+    getLocaleText: customGetLocaleText,
+  });
+  return (
+    <FilterSphereProvider context={context}>
+      <FilterBuilder />
+    </FilterSphereProvider>
+  );
+}
+```
+
+## mapFieldName / mapFilterName
+
+You can customize the field name and filter name by providing the `mapFieldName` and `mapFilterName` functions.
+
+```tsx live
+import {
+  FilterSphereProvider,
+  FilterBuilder,
+  useFilterSphere,
+} from "@fn-sphere/filter";
+import { z } from "zod";
+
+const customMapFieldName = (field: FilterField) => {
+  return field.fieldSchema.description;
+};
+
+const customMapFilterName = (filterSchema: StandardFnSchema) => {
+  return filterSchema.name.toUpperCase();
+};
+
+const schema = z.object({
+  id: z.number().describe("ID"),
+  name: z.string().describe("Name"),
+});
+
+export default function AdvancedFilter() {
+  const { filterRule, predicate, context } = useFilterSphere({
+    schema,
+    mapFilterName: customMapFilterName,
+    mapFieldName: customMapFieldName,
+  });
+  return (
+    <FilterSphereProvider context={context}>
+      <FilterBuilder />
+    </FilterSphereProvider>
+  );
+}
+```
+
+Filter Sphere provides default implementations for the `mapFieldName` and `mapFilterName` functions.
+
+```ts
+export const defaultMapFieldName: (field: FilterField) => string = (field) => {
+  // By default, filter sphere uses the field description as the field name.
+  if (field.fieldSchema.description) {
+    return field.fieldSchema.description;
+  }
+  // If the field description is not provided, the field path is used as the field name.
+  if (field.path.length) {
+    return field.path.join(".");
+  }
+  return "root";
+};
+
+export const defaultMapFilterName: (
+  filterSchema: StandardFnSchema,
+  field: FilterField,
+) => string = (filterSchema) => {
+  return filterSchema.name;
+};
+```

packages/docs/src/content/docs/reference/example.md

@@ -1,11 +1,6 @@
 ---
-title: Example Reference
-description: A reference page in my new Starlight docs site.
+title: 🚧 API
+description: Technical descriptions of the Filter Sphere API
 ---
 
-Reference pages are ideal for outlining how things work in terse and clear terms.
-Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting.
-
-## Further reading
-
-- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework
+WIP