Merge pull request #2 from koeeenig/improve--docs

Improve Docs and Update Examples

README.md

@@ -8,5 +8,4 @@ BlazeKit aims to provide Meta-framework-like Features for Blazor which has been
 - 🖼️ File-based Layout Inheritance
 - 🪄 Auto-Generated Route Parameters
 
-Some more infos can be found at [blazekit.vercel.app](https://blazekit.vercel.app) but keep in mind BlazeKit is work in progress.
-
+Some more infos can be found at [blazekit.dev](https://blazekit.dev) but keep in mind BlazeKit is work in progress.

src/BlazeKit.Site/Assets/layouts.md

@@ -35,14 +35,13 @@ Pages/
 └ Layout.razor
 ```
 
-## Breaking out of Layouts
-Breaking out of layoutspermalink
-The root layout applies to every page of your app — if omitted, it defaults to <slot />. If you want some pages to have a different layout hierarchy than the rest, then you can put your entire app inside one or more groups except the routes that should not inherit the common layouts.
+## Breaking out of layouts
+The root layout applies to every page of your app. If you want some pages to have a different layout hierarchy than the rest, then you can put your entire app inside one or more groups except the routes that should not inherit the common layouts.
 
-In the example above, the /admin route does not inherit either the (app) or (marketing) layouts.
+In the example above, the /Admin route does not inherit either the (App) or (Marketing) layouts.
 
-+page@permalink
-Pages can break out of the current layout hierarchy on a route-by-route basis. Suppose we have an /item/[id]/embed route inside the (app) group from the previous example:
+### Page@
+Pages can break out of the current layout hierarchy on a route-by-route basis. Suppose we have an /Item/[id]/Embed route inside the (App) group from the previous example:
 ```none
 Pages/
 ├ (App)/
@@ -55,11 +54,11 @@ Pages/
 │ └ Layout.razor
 └ Layout.razor
 ```
-Ordinarily, this would inherit the root layout, the (app) layout, the item layout and the [id] layout. We can reset to one of those layouts by appending @ followed by the segment name — or, for the root layout, the empty string. In this example, we can choose from the following options:
+Ordinarily, this would inherit the root layout, the **(App) layout**, the **item layout** and the **[Id] layout**. We can reset to one of those layouts by appending @ followed by the segment name — or, for the root layout, the empty string. In this example, we can choose from the following options:
 
-- Page@[id].razor - inherits from Pages/(App)/Item/[id]/Layout.razor
-- Page@item.razor - inherits from Pages/(App)/Item/Layout.razor
-- Page@(app).razor - inherits from Pages/(App)/Layout.razor
+- Page@[Id].razor - inherits from Pages/(App)/Item/[id]/Layout.razor
+- Page@Item.razor - inherits from Pages/(App)/Item/Layout.razor
+- Page@(App).razor - inherits from Pages/(App)/Layout.razor
 - Page@.razor - inherits from Pages/Layout.razor
 
 ```none
@@ -74,7 +73,9 @@ Pages/
 │ └ Layout.razor
 └ Layout.razor
 ```
-Like pages, layouts can themselves break out of their parent layout hierarchy, using the same technique. For example, a +layout@.svelte component would reset the hierarchy for all its child routes.
+## Layout@
+
+Like pages, layouts can themselves break out of their parent layout hierarchy, using the same technique. For example, a Layout@.razor component would reset the hierarchy for all its child routes.
 ```none
 Pages/
 ├ (App)/
@@ -84,7 +85,7 @@ Pages/
 │ │ │ │ └ Page.razor  // uses (App)/Item/[Id]/Layout.razor
 │ │ │ ├ Layout.razor  // inherits from (App)/Item/Layout@.razor
 │ │ │ └ Page.razor    // uses (App)/Item/Layout@.razor
-│ │ └ Layout.razor   // inherits from root layout, skipping (App)/Layout.razor
+│ │ └ Layout@.razor   // inherits from root layout, skipping (App)/Layout.razor
 │ └ Layout.razor
 └ Layout.razor
 ```

src/BlazeKit.Site/Pages/(Public)/Items/Details/Page@.razor

@@ -0,0 +1,5 @@
+<PageTitle>BlazeKit - Breaking out of layout demo</PageTitle>
+<h1>Details Page</h1>
+
+<p>This site is an example for beaking out of layouts. The site is located in Pages/(Public)/Items/Details which would imply that the layouts from (Public), Items and Details will be applied to the page.</p>
+<p>Since we named the file Page@@.razor the layout inheritence will be omitted and the site will inherit the layout from Pages/Layout.razor file.</p>

src/BlazeKit.Site/Pages/(Public)/Items/Details/[Id]/Page.razor

@@ -45,7 +45,9 @@
         Router.NavigateTo($"/items/details/{Id}", forceLoad: true);
     }
 }
-<p>This route uses nested layouts and a aut-generated route parameter.</p>
+
+<PageTitle>BlazeKit - Nested layouts and route parameters</PageTitle>
+<p>This route uses nested layouts and auto-generated route parameter.</p>
 <p>The layout for <strong>Pages/(Public)/Items/Details/[Id]/Page.razor</strong> is composed from:</p>
 <ul>
     <li><i>Pages/(Public)/Items/Details/Layout.razor</i></li>

src/BlazeKit.Site/Pages/(Public)/Items/Layout.razor

@@ -1,5 +1,5 @@
 @inherits LayoutComponentBase
-<h3>Layout in Foo</h3>
+<h3>Layout in Items</h3>
 @Body
 @code {
 

src/BlazeKit.Site/Pages/Page.razor

@@ -28,6 +28,9 @@
     <li>
         <a href="/items/details/2?foo=bar  ">Nested Layouts Demo with Route Params</a>
     </li>
+    <li>
+        <a href="/items/details  ">Breaking out of layouts Demo</a>
+    </li>
 </ul>
 
 <h2>🛠️ Todo's</h2>

src/BlazeKit.Site/Pages/Reactivity/Basic/Page.razor

@@ -48,6 +48,9 @@
                     if (counter.Value > 0 && counter.Value % 2 == 0)
                     {
                         booms++;
+                        // since booms in not a signal, we need to notify the UI manually
+                        // this is required if the counter updates in background task
+                        InvokeAsync(StateHasChanged);
                     }
                 }
             );
@@ -124,19 +127,19 @@
     @AsHtml("ISignal<int> counter = new BlzState<int>(0, this)").Value
     @AsHtml(@"// Create a derived State
     ISignal<int> doubled =
-        new BlzComputed<int, int>(
-            counter,
+        new Derived<int>(
             () => counter.Value * 2,
             this
         );").Value
     @AsHtml(@"// Create an Effect
-    new Effect<int>(() => {
+    new Effect(() => {
             if(counter.Value > 0 && counter.Value % 5 == 0)
             {
+                // since booms in not a signal, we need to notify the UI manually
+                // this is required if the counter updates in background task
                 booms++;
             }
-        },
-        counter
+        }
     );").Value
 }
 

src/BlazeKit/Layout/ClosestLayout.cs

@@ -1,4 +1,3 @@
-using Microsoft.CodeAnalysis.CSharp.Syntax;
 using System;
 using System.IO;
 using System.Linq;
@@ -9,39 +8,71 @@ public sealed class ClosestLayout : Lazy<string>
     {
         public ClosestLayout(string file, Action<string> log, bool skipSameDirectory = false, string root = "pages") : base(() =>
         {
-            var rootFolder = file.ToLower().Substring(0, file.ToLower().IndexOf(root) + root.Length);
-            rootFolder = file.Substring(0, rootFolder.Length);
-            var name = "";
-            var fi = new FileInfo(file);
-            if (IsBreakout(fi)) {
-                log($"The layout file '{fi.Name}' breaks out of the inheritence chain");
-                // find breakout layout
-                var breakoutLayout = Path.GetFileNameWithoutExtension(fi.FullName).Split('@')[1];
-                var layoutPath = SegmentFolder(breakoutLayout, rootFolder);
-                //var layoutPath = fi.FullName.Substring(0,fi.FullName.IndexOf(breakoutLayout));
-                if(string.IsNullOrEmpty(layoutPath.Name))
-                {
+            try {
+                var rootFolder = file.ToLower().Substring(0, file.ToLower().IndexOf(root) + root.Length);
+                rootFolder = file.Substring(0, rootFolder.Length);
+
+                var name = "";
+                var fi = new FileInfo(file);
+                if (IsBreakout(fi)) {
+                    log($"The Page/Layout '{fi.Name}' breaks out of the inheritence chain");
+                    // find breakout layout
+                    var breakoutLayout = Path.GetFileNameWithoutExtension(fi.FullName).Split('@')[1];
+
                     // sreach for layout at root
-                    layoutPath = new FileInfo(file.ToLower().Substring(0, file.ToLower().IndexOf(root) + root.Length));
+                    var layoutPath = new FileInfo(file.ToLower().Substring(0, file.ToLower().IndexOf(root) + root.Length));
                     layoutPath = new FileInfo(file.Substring(0, layoutPath.FullName.Length));
+
+                    if(!string.IsNullOrEmpty(breakoutLayout))
+                    {
+                        layoutPath = SegmentFolder(breakoutLayout, rootFolder);
+                        //var layoutPath = fi.FullName.Substring(0,fi.FullName.IndexOf(breakoutLayout));
+                        if(string.IsNullOrEmpty(layoutPath.Name))
+                        {
+                            // sreach for layout at root
+                            layoutPath = new FileInfo(file.ToLower().Substring(0, file.ToLower().IndexOf(root) + root.Length));
+                            layoutPath = new FileInfo(file.Substring(0, layoutPath.FullName.Length));
+                        } else
+                        {
+                            layoutPath = SegmentFolder(breakoutLayout, rootFolder);
+                        }
+                        log($"Searching for breakout layout in: {layoutPath}");
+                        if(HasLayout(layoutPath.DirectoryName))
+                        {
+                            name = LayoutOf(layoutPath.DirectoryName).FullName;
+                        } else
+                        {
+                            log($"Could not find breakout layout in: {layoutPath}");
+                            var dir = fi.Directory;
+
+                            if (skipSameDirectory && !IsRoot(dir.Name, root))
+                            {
+                                dir = dir.Parent;
+                            }
+                            else if (skipSameDirectory && IsRoot(dir.Name, root))
+                            {
+                                return "";
+                            }
+
+                            // check if the directory contains a Layout file
+                            while (!HasLayout(dir.FullName))
+                            {
+                                dir = dir.Parent;
+                            }
+                            // we found a layout file
+                            name = LayoutOf(dir.FullName).FullName;
+                        }
+                    } else {
+                        name = LayoutOf(rootFolder).FullName;
+                    }
                 } else
                 {
-                    layoutPath = SegmentFolder(breakoutLayout, rootFolder);
-                }
-                log($"Searching for breakout layout in: {layoutPath}");
-                if(HasLayout(layoutPath.DirectoryName))
-                {
-                    name = LayoutOf(layoutPath.DirectoryName).FullName;
-                } else
-                {
-                    log($"Could not find breakout layout in: {layoutPath}");
                     var dir = fi.Directory;
 
-                    if (skipSameDirectory && !IsRoot(dir.Name, root))
+                    if(skipSameDirectory && !IsRoot(dir.Name,root))
                     {
                         dir = dir.Parent;
-                    }
-                    else if (skipSameDirectory && IsRoot(dir.Name, root))
+                    } else if(skipSameDirectory && IsRoot(dir.Name,root))
                     {
                         return "";
                     }
@@ -54,31 +85,17 @@ public ClosestLayout(string file, Action<string> log, bool skipSameDirectory = f
                     // we found a layout file
                     name = LayoutOf(dir.FullName).FullName;
                 }
-            } else
-            {
-                var dir = fi.Directory;
-
-                if(skipSameDirectory && !IsRoot(dir.Name,root))
-                {
-                    dir = dir.Parent;
-                } else if(skipSameDirectory && IsRoot(dir.Name,root))
-                {
-                    return "";
-                }
 
-                // check if the directory contains a Layout file
-                while (!HasLayout(dir.FullName))
-                {
-                    dir = dir.Parent;
-                }
-                // we found a layout file
-                name = LayoutOf(dir.FullName).FullName;
+                log($"Found layout file: {name}");
+                //var className = $"{new NamespaceSegments(name,root).Value}.{new SanititizedNamespace(Path.GetFileNameWithoutExtension(name)).Value}";
+                var className = new SanititizedNamespace($"{new NamespaceSegments(name, root).Value}.{Path.GetFileNameWithoutExtension(name)}").Value;
+                return className;
+            } catch(Exception ex)
+            {
+                log(ex.ToString());
+                throw new InvalidOperationException($"Could not find layout for {file}");
             }
 
-            log($"Found layout file: {name}");
-            //var className = $"{new NamespaceSegments(name,root).Value}.{new SanititizedNamespace(Path.GetFileNameWithoutExtension(name)).Value}";
-            var className = new SanititizedNamespace($"{new NamespaceSegments(name, root).Value}.{Path.GetFileNameWithoutExtension(name)}").Value;
-            return className;
         })
         { }
 

src/BlazeKit/NamespaceSegments.cs

@@ -7,9 +7,13 @@ internal class NamespaceSegments : Lazy<string>
     {
         public NamespaceSegments(string path, string root) : base(() =>
         {
-            var structure = path.Substring(path.ToLower().IndexOf(root));
-            var segments = structure.Split(new char[] { System.IO.Path.DirectorySeparatorChar }, StringSplitOptions.RemoveEmptyEntries).Reverse().Skip(1).Reverse();//.Select(s => new SanititizedNamespace(s).Value);
-            return new SanititizedNamespace(string.Join(".", segments)).Value;
+            var result = new SanititizedNamespace(root).Value;
+            if(path.ToLower().IndexOf(root) >= 0) {
+                var structure = path.Substring(path.ToLower().IndexOf(root));
+                var segments = structure.Split(new char[] { System.IO.Path.DirectorySeparatorChar }, StringSplitOptions.RemoveEmptyEntries).Reverse().Skip(1).Reverse();
+                result = new SanititizedNamespace(string.Join(".", segments)).Value;
+            }
+            return result;
         })
         { }
     }